From 294945fc99a8dcae731448de58d075f6006ebcaa Mon Sep 17 00:00:00 2001
From: Richard Elberger <elberger@amazon.com>
Date: Wed, 24 Jun 2026 09:12:22 -0400
Subject: [PATCH] armv9: document Armv9 port MISRA deviations in MISRA.md

Add three new deviation entries for the ARM_AARCH64_ARMV9 port:

- Directive 4.3 (inline assembly): required to access AArch64 system
  registers with no C equivalent; confined to the port layer
- Rule 5.8 (identifier reuse): pvPortMalloc/vPortFree macro redirect
  to MTE-tagged wrappers, isolating tagging logic in the port
- Rule 11.6 (pointer-to-integer cast): MTE tag stripping requires
  masking pointer bits 56-59 via uintptr_t to recover canonical address
---
 MISRA.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/MISRA.md b/MISRA.md
index 5016e7b27..3cf3d1197 100644
--- a/MISRA.md
+++ b/MISRA.md
@@ -18,6 +18,16 @@ with ( Assuming rule 8.4 violation; with justification in point 1 ):
 grep 'MISRA Ref 8.4.1' . -rI
 ```
 
+#### Dir 4.3
+
+MISRA C:2012 Dir 4.3: Assembly language shall be encapsulated and isolated.
+
+_Ref 4.3.1_
+ - AArch64 port files (portable/GCC/ARM_AARCH64_ARMV9/) use inline assembly
+   to access system registers (GIC, generic timer, PAC keys, MTE, SVE
+   configuration) that have no C-language equivalent. Assembly is confined to
+   the port layer and isolated from application code.
+
 #### Dir 4.7
 
 MISRA C:2012 Dir 4.7: If a function returns error information, then that error
@@ -116,6 +126,31 @@ _Ref 11.5.5_
    because data storage buffers are implemented as uint8_t arrays for the
    ease of sizing, alignment and access.
 
+#### Rule 5.8
+
+MISRA C:2012 Rule 5.8: Identifiers that define objects or functions with
+external linkage shall be unique.
+
+_Ref 5.8.1_
+ - The Armv9 port (portable/GCC/ARM_AARCH64_ARMV9/portmacro.h) defines macros
+   that redirect `pvPortMalloc` and `vPortFree` to MTE-tagged wrapper functions
+   when `configARMV9_MTE_HEAP == 1`. This keeps MTE heap tagging logic isolated
+   in the port without modifying shared upstream kernel files. An alternative
+   that eliminates this deviation (integrating tagging into heap_4.c) is
+   documented in the source.
+
+#### Rule 11.6
+
+MISRA C:2012 Rule 11.6: A cast shall not be performed between a pointer to void
+and an arithmetic type.
+
+_Ref 11.6.1_
+ - The Armv9 MTE port (portable/GCC/ARM_AARCH64_ARMV9/mte_port.c) casts
+   between pointer and uintptr_t to strip the MTE tag bits (top byte) from
+   tagged pointers before passing them to the underlying allocator. This is
+   required because MTE tags are encoded in pointer bits 56-59 and must be
+   removed to recover the canonical address.
+
 #### Rule 14.3
 
 MISRA C-2012 Rule 14.3: Controlling expressions shall not be invariant.