Updating docs (#1619)

Co-authored-by: Miłosz Plichta <milosz.plichta@arm.com>

CMSIS/DoxyGen/Core/src/Ref_MPU8.txt

@@ -11,14 +11,14 @@ The MPU is used to prevent from illegal memory accesses that are typically cause
 int main() 
 {
   // Set Region 0 using Attr 0
-  ARM_MPU_SetMemAttr(0UL, ARM_MPU_ATTR(       /* Normal memory */
-    ARM_MPU_ATTR_MEMORY_(0UL, 1UL, 1UL, 1UL), /* Outer Write-Back transient with read and write allocate */
-    ARM_MPU_ATTR_MEMORY_(0UL, 0UL, 1UL, 1UL)  /* Inner Write-Through transient with read and write allocate */
+  ARM_MPU_SetMemAttr(0UL, ARM_MPU_ATTR( /* Normal memory */
+    MPU_ATTR_NORMAL_OUTER_WT_TR_RA_WA,  /* Outer Write-Back transient with read and write allocate */
+    MPU_ATTR_NORMAL_INNER_WT_TR_RA_WA   /* Inner Write-Through transient with read and write allocate */
   ));
   
   ARM_MPU_SetRegion(0UL,
-    ARM_MPU_RBAR(0x08000000UL, ARM_MPU_SH_NON, 0UL, 1UL, 1UL),  /* Non-shareable, read/write, non-privileged, execute-never */
-    ARM_MPU_RLAR(0x080FFFFFUL, 0UL)                             /* 1MB memory block using Attr 0 */
+    ARM_MPU_RBAR(0x08000000UL, ARM_MPU_SH_NON, ARM_MPU_AP_RW, ARM_MPU_AP_NP, ARM_MPU_XN),  /* Non-shareable, read/write, non-privileged, execute-never */
+    ARM_MPU_RLAR(0x080FFFFFUL, MAIR_ATTR(0))                        /* 1MB memory block using Attr 0 */
   );
   
   ARM_MPU_Enable(0);
@@ -38,11 +38,11 @@ int main()
 /** \brief Attribute for non-cacheable, normal memory */
 #define ARM_MPU_ATTR_NON_CACHEABLE                    ( 4U )
 
-/** \brief Attribute for normal memory (outer and inner)
-* \param NT Non-Transient: Set to 1 for non-transient data.
-* \param WB Write-Back: Set to 1 to use write-back update policy.
-* \param RA Read Allocation: Set to 1 to use cache allocation on read miss.
-* \param WA Write Allocation: Set to 1 to use cache allocation on write miss.
+/** \brief Attribute for Normal memory, Outer and Inner cacheability.
+* \param NT Non-Transient: Set to 1 for Non-transient data. Set to 0 for Transient data.
+* \param WB Write-Back: Set to 1 to use a Write-Back policy. Set to 0 to use a Write-Through policy.
+* \param RA Read Allocation: Set to 1 to enable cache allocation on read miss. Set to 0 to disable cache allocation on read miss.
+* \param WA Write Allocation: Set to 1 to enable cache allocation on write miss. Set to 0 to disable cache allocation on write miss.
 */
 #define ARM_MPU_ATTR_MEMORY_(NT, WB, RA, WA)
 
@@ -58,12 +58,45 @@ int main()
 /** \brief Device memory type Gathering, Re-ordering, Early Write Acknowledgement */
 #define ARM_MPU_ATTR_DEVICE_GRE
 
+/** \brief Normal memory outer-cacheable and inner-cacheable attributes
+* WT = Write Through, WB = Write Back, TR = Transient, RA = Read-Allocate, WA = Write Allocate
+*/
+#define MPU_ATTR_NORMAL_OUTER_NON_CACHEABLE
+#define MPU_ATTR_NORMAL_OUTER_WT_TR_RA
+#define MPU_ATTR_NORMAL_OUTER_WT_TR_WA
+#define MPU_ATTR_NORMAL_OUTER_WT_TR_RA_WA
+#define MPU_ATTR_NORMAL_OUTER_WT_RA
+#define MPU_ATTR_NORMAL_OUTER_WT_WA
+#define MPU_ATTR_NORMAL_OUTER_WT_RA_WA
+#define MPU_ATTR_NORMAL_OUTER_WB_TR_RA
+#define MPU_ATTR_NORMAL_OUTER_WB_TR_WA
+#define MPU_ATTR_NORMAL_OUTER_WB_TR_RA_WA
+#define MPU_ATTR_NORMAL_OUTER_WB_RA
+#define MPU_ATTR_NORMAL_OUTER_WB_WA
+#define MPU_ATTR_NORMAL_OUTER_WB_RA_WA
+#define MPU_ATTR_NORMAL_INNER_NON_CACHEABLE
+#define MPU_ATTR_NORMAL_INNER_WT_TR_RA
+#define MPU_ATTR_NORMAL_INNER_WT_TR_WA
+#define MPU_ATTR_NORMAL_INNER_WT_TR_RA_WA
+#define MPU_ATTR_NORMAL_INNER_WT_RA
+#define MPU_ATTR_NORMAL_INNER_WT_WA
+#define MPU_ATTR_NORMAL_INNER_WT_RA_WA
+#define MPU_ATTR_NORMAL_INNER_WB_TR_RA
+#define MPU_ATTR_NORMAL_INNER_WB_TR_WA
+#define MPU_ATTR_NORMAL_INNER_WB_TR_RA_WA
+#define MPU_ATTR_NORMAL_INNER_WB_RA
+#define MPU_ATTR_NORMAL_INNER_WB_WA
+#define MPU_ATTR_NORMAL_INNER_WB_RA_WA
+
 /** \brief Memory Attribute
 * \param O Outer memory attributes
 * \param I O == ARM_MPU_ATTR_DEVICE: Device memory attributes, else: Inner memory attributes
 */
 #define ARM_MPU_ATTR(O, I)
 
+/**
+ * Shareability
+ */
 /** \brief Normal memory non-shareable  */
 #define ARM_MPU_SH_NON
 
@@ -73,6 +106,32 @@ int main()
 /** \brief Normal memory inner shareable  */
 #define ARM_MPU_SH_INNER
 
+/**
+ * Access permissions
+ * AP = Access permission, RO = Read-only, RW = Read/Write, NP = Any privilege, PO = Privileged code only
+ */
+/** \brief Normal memory, read/write */
+#define ARM_MPU_AP_RW
+
+/** \brief Normal memory, read-only */
+#define ARM_MPU_AP_RO
+
+/** \brief Normal memory, any privilege level */
+#define ARM_MPU_AP_NP
+
+/** \brief Normal memory, privileged access only */
+#define ARM_MPU_AP_PO
+
+/*
+ * Execute-never
+ * XN = Execute-never, EX = Executable
+ */
+/** \brief Normal memory, Execution only permitted if read permitted */
+#define ARM_MPU_XN
+
+/** \brief Normal memory, Execution only permitted if read permitted */
+#define ARM_MPU_EX
+
 /** \brief Memory access permissions
 * \param RO Read-Only: Set to 1 for read-only memory.
 * \param NP Non-Privileged: Set to 1 for non-privileged memory.
@@ -82,15 +141,11 @@ int main()
 /** \brief Region Base Address Register value
 * \param BASE The base address bits [31:5] of a memory region. The value is zero extended. Effective address gets 32 byte aligned.
 * \param SH Defines the Shareability domain for this memory region.
-* \param RO Read-Only: Set to 1 for a read-only memory region.
-* \param NP Non-Privileged: Set to 1 for a non-privileged memory region.
-* \param XN eXecute Never: Set to 1 for a non-executable memory region.
+* \param RO Read-Only: Set to 1 for a read-only memory region. Set to 0 for a read/write memory region.
+* \param NP Non-Privileged: Set to 1 for a non-privileged memory region. Set to 0 for privileged memory region.
+* \param XN eXecute Never: Set to 1 for a non-executable memory region. Set to 0 for an executable memory region.
 */
-#define ARM_MPU_RBAR(BASE, SH, RO, NP, XN) \
-  ((BASE & MPU_RBAR_BASE_Msk) | \
-  ((SH << MPU_RBAR_SH_Pos) & MPU_RBAR_SH_Msk) | \
-  ((ARM_MPU_AP_(RO, NP) << MPU_RBAR_AP_Pos) & MPU_RBAR_AP_Msk) | \
-  ((XN << MPU_RBAR_XN_Pos) & MPU_RBAR_XN_Msk))
+#define ARM_MPU_RBAR(BASE, SH, RO, NP, XN)
 
 /** \brief Region Limit Address Register value
 * \param LIMIT The limit address bits [31:5] for this memory region. The value is one extended.
@@ -98,6 +153,13 @@ int main()
 */
 #define ARM_MPU_RLAR(LIMIT, IDX)
 
+/** \brief Region Limit Address Register with PXN value
+* \param LIMIT The limit address bits [31:5] for this memory region. The value is one extended.
+* \param PXN Privileged execute never. Defines whether code can be executed from this privileged region.
+* \param IDX The attribute index to be associated with this memory region.
+*/
+#define ARM_MPU_RLAR_PXN(LIMIT, PXN, IDX)
+
 /**
 * Struct for a single MPU Region
 */
@@ -105,7 +167,13 @@ typedef struct {
   uint32_t RBAR;                   /*!< Region Base Address Register value */
   uint32_t RLAR;                   /*!< Region Limit Address Register value */
 } ARM_MPU_Region_t;
-    
+
+/**
+  \brief  Read MPU Type Register
+  \return Number of MPU regions
+*/
+__STATIC_INLINE uint32_t ARM_MPU_TYPE()
+
 /** Enable the MPU.
 * \param MPU_Control Default access permissions for unconfigured regions.
 */
@@ -205,11 +273,11 @@ __STATIC_INLINE void ARM_MPU_LoadEx(MPU_Type* mpu, uint32_t rnr, ARM_MPU_Region_
 * \code
 * const ARM_MPU_Region_t mpuTable[1][4] = {
 *   {
-*     //                     BASE          SH              RO   NP   XN                         LIMIT         ATTR 
-*     { .RBAR = ARM_MPU_RBAR(0x08000000UL, ARM_MPU_SH_NON, 0UL, 1UL, 0UL), .RLAR = ARM_MPU_RLAR(0x080FFFFFUL, 0UL) },
-*     { .RBAR = ARM_MPU_RBAR(0x20000000UL, ARM_MPU_SH_NON, 0UL, 1UL, 1UL), .RLAR = ARM_MPU_RLAR(0x20007FFFUL, 0UL) },
-*     { .RBAR = ARM_MPU_RBAR(0x40020000UL, ARM_MPU_SH_NON, 0UL, 1UL, 1UL), .RLAR = ARM_MPU_RLAR(0x40021FFFUL, 1UL) },
-*     { .RBAR = ARM_MPU_RBAR(0x40022000UL, ARM_MPU_SH_NON, 0UL, 1UL, 1UL), .RLAR = ARM_MPU_RLAR(0x40022FFFUL, 1UL) }
+*     //                     BASE          SH              RO             NP             XN                                LIMIT         ATTR 
+*     { .RBAR = ARM_MPU_RBAR(0x08000000UL, ARM_MPU_SH_NON, ARM_MPU_AP_RO, ARM_MPU_AP_NP, ARM_MPU_XN), .RLAR = ARM_MPU_RLAR(0x080FFFFFUL, MAIR_ATTR(0)) },
+*     { .RBAR = ARM_MPU_RBAR(0x20000000UL, ARM_MPU_SH_NON, ARM_MPU_AP_RO, ARM_MPU_AP_NP, ARM_MPU_XN), .RLAR = ARM_MPU_RLAR(0x20007FFFUL, MAIR_ATTR(0)) },
+*     { .RBAR = ARM_MPU_RBAR(0x40020000UL, ARM_MPU_SH_NON, ARM_MPU_AP_RO, ARM_MPU_AP_NP, ARM_MPU_XN), .RLAR = ARM_MPU_RLAR(0x40021FFFUL, MAIR_ATTR(1)) },
+*     { .RBAR = ARM_MPU_RBAR(0x40022000UL, ARM_MPU_SH_NON, ARM_MPU_AP_RO, ARM_MPU_AP_NP, ARM_MPU_XN), .RLAR = ARM_MPU_RLAR(0x40022FFFUL, MAIR_ATTR(1)) }
 *   }
 * };
 *