[PATCH v2] misra: add deviations of MISRA C Rule 5.5

[Dmytro Prokopchuk1 <dmytro_prokopchuk1@xxxxxxxx>]

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

Update ECLAIR configuration to deviate clashes:
specify the macros that should be ignored.
Update deviations.rst and rules.rst accordingly.

Signed-off-by: Dmytro Prokopchuk <dmytro_prokopchuk1@xxxxxxxx>
---
v1: 
https://patchew.org/Xen/7e1c381d6fab6d38bb2a5484d5fac5e863ba135f.1752689112.git.dmytro._5Fprokopchuk1@xxxxxxxx/

Changes in v2:
- changed Eclair configs (option '-reports' replaced with '-ignored_macros')
- updated deviations.rst
- updated rules.rst
- updated commit message

Test CI pipeline: 
https://gitlab.com/xen-project/people/dimaprkp4k/xen/-/pipelines/1948281147

MC3A2.R5.5 violations:
ARM - 0
X86 - 328
---
 .../eclair_analysis/ECLAIR/deviations.ecl     | 16 ++++++++++++
 docs/misra/deviations.rst                     | 25 +++++++++++++++++++
 docs/misra/rules.rst                          | 19 ++++++++++++++
 3 files changed, 60 insertions(+)

diff --git a/automation/eclair_analysis/ECLAIR/deviations.ecl 
b/automation/eclair_analysis/ECLAIR/deviations.ecl
index 483507e7b9..13e1511a7c 100644
--- a/automation/eclair_analysis/ECLAIR/deviations.ecl
+++ b/automation/eclair_analysis/ECLAIR/deviations.ecl
@@ -117,6 +117,22 @@ it defines would (in the common case) be already defined. 
Peer reviewed by the c
 -config=MC3A2.R5.5,reports+={deliberate, 
"any_area(decl(kind(function))||any_loc(macro(name(memcpy||memset||memmove))))&&any_area(any_loc(file(^xen/common/libelf/libelf-private\\.h$)))"}
 -doc_end
 
+-doc_begin="Clashes between bitops functions and macros names are deliberate.
+These macros are needed for input validation and error handling."
+-config=MC3A2.R5.5,ignored_macros+="name(__test_and_set_bit||__test_and_clear_bit||__test_and_change_bit||test_bit||set_bit||clear_bit||change_bit||test_and_set_bit||test_and_clear_bit||test_and_change_bit)"
+-doc_end
+
+-doc_begin="Clashes between 'pirq_cleanup_check' function and macro names are 
deliberate.
+The purpose is to ensure that the specific cleanup action
+('pirq_cleanup_check') is performed conditionally when the parameter 'event 
channel number' equals zero, otherwise it does nothing."
+-config=MC3A2.R5.5,ignored_macros+="name(pirq_cleanup_check)"
+-doc_end
+
+-doc_begin="Clashes between grant table functions and macros names are 
deliberate.
+These macros address differences in argument count during compile-time, 
effectively discarding unused parameters to avoid warnings or errors related to 
unused arguments."
+-config=MC3A2.R5.5,ignored_macros+="name(update_gnttab_par||parse_gnttab_limit)"
+-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 e78179fcb8..c6a0c084bf 100644
--- a/docs/misra/deviations.rst
+++ b/docs/misra/deviations.rst
@@ -142,6 +142,31 @@ Deviations related to MISRA C:2012 Rules:
        memmove.
      - Tagged as `deliberate` for ECLAIR.
 
+   * - R5.5
+     - Clashes between bitops functions and macros names are deliberate and are
+       needed for input validation and error handling, ensures that the size of
+       the object being pointed to by 'addr' meets the minimum requirements for
+       the bit operation, preventing unsafe operations on improperly sized data
+       types that could lead to undefined behavior or memory corruption.
+       The macros encapsulate this conditional logic into a single, reusable 
form;
+       which simplifies the code, avoids redundant function call.
+     - Specified macros should be ignored.
+
+   * - R5.5
+     - Clashes between 'pirq_cleanup_check' function and macro names are 
deliberate.
+       The purpose is to ensure that the specific cleanup action 
('pirq_cleanup_check')
+       is performed conditionally when the parameter 'event channel number' 
equals
+       zero, otherwise it does nothing.
+       This approach simplifies the code, avoids redundant function call.
+     - Specified macro should be ignored.
+
+   * - R5.5
+     - Clashes between grant table functions and macros names are deliberate.
+       These macros address differences in argument count during compile-time,
+       effectively discarding unused parameters to avoid warnings or errors
+       related to unused arguments.
+     - Specified macro should be ignored.
+
    * - 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 3e014a6298..3f288364b1 100644
--- a/docs/misra/rules.rst
+++ b/docs/misra/rules.rst
@@ -196,6 +196,25 @@ maintainers if you want to suggest a change.
            #define f(x, y) f(x, y)
            void f(int x, int y);
 
+       Clashes between bitops functions and macros names are allowed
+       when they are used for input validation and error handling.
+       Example::
+
+           static inline void set_bit(int nr, volatile void *addr)
+           {
+               asm volatile ( "lock btsl %1,%0"
+                              : "+m" (ADDR) : "Ir" (nr) : "memory");
+           }
+           #define set_bit(nr, addr) ({                            \
+               if ( bitop_bad_size(addr) ) __bitop_bad_size();     \
+               set_bit(nr, addr);                                  \
+           })
+
+       Clashes between 'pirq_cleanup_check' function and macro names
+       are allowed.
+
+       Clashes between grant table functions and macros names are allowed.
+
    * - `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