MPU Driver. More...

Files
file	hw_mpu.h
	Definition of API for the Memory Protection Unit (MPU) Low Level Driver.

Data Structures
struct	mpu_region_config
	Memory Region Configuration. More...

Enumerations
enum	HW_MPU_REGION_NUM { HW_MPU_REGION_NONE = MPU_REGION_NONE, HW_MPU_REGION_0 = MPU_REGION_0, HW_MPU_REGION_1 = MPU_REGION_1, HW_MPU_REGION_2 = MPU_REGION_2, HW_MPU_REGION_3 = MPU_REGION_3, HW_MPU_REGION_4 = MPU_REGION_4, HW_MPU_REGION_5 = MPU_REGION_5, HW_MPU_REGION_6 = MPU_REGION_6, HW_MPU_REGION_7 = MPU_REGION_7 }
	Region Definitions. More...

enum	HW_MPU_XN { HW_MPU_XN_FALSE = 0x00, HW_MPU_XN_TRUE = 0x01 }
	Executable Region. More...

enum	HW_MPU_APH_RO { HW_MPU_APH_RO_RW = 0x00, HW_MPU_APH_RO_RO = 0x01 }
	Region Read/Write or Read Only. More...

enum	HW_MPU_APL_NP { HW_MPU_APL_NP_PRIVRW = 0x00, HW_MPU_APL_NP_RW = 0x01 }
	Privileged or Non-Privileged access. More...

enum	HW_MPU_AP { HW_MPU_AP_PRIVRW = ARM_MPU_AP_(HW_MPU_APH_RO_RW, HW_MPU_APL_NP_PRIVRW), HW_MPU_AP_RW = ARM_MPU_AP_(HW_MPU_APH_RO_RW, HW_MPU_APL_NP_RW), HW_MPU_AP_PRIVRO = ARM_MPU_AP_(HW_MPU_APH_RO_RO, HW_MPU_APL_NP_PRIVRW), HW_MPU_AP_RO = ARM_MPU_AP_(HW_MPU_APH_RO_RO, HW_MPU_APL_NP_RW) }
	Access Permissions. More...

enum	HW_MPU_ATTR_INDEX { HW_MPU_ATTR_INDEX_0, HW_MPU_ATTR_INDEX_1, HW_MPU_ATTR_INDEX_2, HW_MPU_ATTR_INDEX_3, HW_MPU_ATTR_INDEX_4, HW_MPU_ATTR_INDEX_5, HW_MPU_ATTR_INDEX_6, HW_MPU_ATTR_INDEX_7 }
	Memory attributes. More...

enum	HW_MPU_SH { HW_MPU_SH_NS = ARM_MPU_SH_NON, HW_MPU_SH_OS = ARM_MPU_SH_OUTER, HW_MPU_SH_IS = ARM_MPU_SH_INNER }
	Shareability. More...

enum	HW_MPU_ATTR { HW_MPU_ATTR_DEVICE = 0x00, HW_MPU_ATTR_NORMAL = 0x44 }
	Memory Type. More...

Functions
__STATIC_FORCEINLINE void	hw_mpu_hardfault_nmi_handlers_enable (bool hfnmiena)
	Enables/Disables the operation of MPU during hard fault, NMI, and FAULTMASK handlers. More...

__STATIC_FORCEINLINE void	hw_mpu_privileged_background_access_enable (bool privdefena)
	Enables/Disables Privileged Background Access. More...

__STATIC_FORCEINLINE void	hw_mpu_enable (bool privdefena)
	Initializes the MPU by disabling its operation during faults, defining the background region privilege access and finally by enabling the actual HW block. More...

__STATIC_FORCEINLINE void	hw_mpu_disable (void)
	Disables the MPU. More...

__STATIC_FORCEINLINE bool	hw_mpu_is_enabled (void)
	Checks if MPU is enabled. More...

void	hw_mpu_set_attribute_indirection (HW_MPU_REGION_NUM region_num, HW_MPU_ATTR_INDEX attr)
	Configures an MPU attribute indirection. More...

void	hw_mpu_reset_attribute_indirections ()
	Resets all MPU attribute indirections. MPU Attribute Index pattern is returned to one-to-one configuration.

void	hw_mpu_config_region (HW_MPU_REGION_NUM region_num, mpu_region_config *cfg)
	Configures an MPU region. Region's start and end addresses will be aligned to 32 byte boundary. The start address is ANDed with 0xFFFFFFE0 whereas the end address is ORed with 0x1F. More...

void	hw_mpu_fetch_region_configuration (HW_MPU_REGION_NUM region_num, mpu_region_config *cfg)
	Fetches the configuration of an MPU region. More...

Detailed Description

MPU Driver.

Enumeration Type Documentation

◆ HW_MPU_AP

enum HW_MPU_AP

Access Permissions.

Attribute regarding the access permission (AP) of a particular region with respect to privilege level and read/write capabilities. Depending on the privilege configuration an application can access or not CPU features such as memory, I/O, enable/disable interrupts, setup the NVIC, etc. By system design it can be imperative to restrict an application by defining accordingly the MPU settings for the corresponding region. This enumerator is the superposition of HW_MPU_APH_RO and HW_MPU_APL_NP and is provided for cases where the combined AP section is required.

Enumerator
HW_MPU_AP_PRIVRW	Read/write by privileged code only
HW_MPU_AP_RW	Read/write by any privilege level
HW_MPU_AP_PRIVRO	Read-only by privileged code only
HW_MPU_AP_RO	Read-only by any privilege level

◆ HW_MPU_APH_RO

enum HW_MPU_APH_RO

Region Read/Write or Read Only.

Attribute regarding the access permission (AP) of a particular region with respect to privilege level and read/write capabilities.

Enumerator
HW_MPU_APH_RO_RW	Read/write
HW_MPU_APH_RO_RO	Read-only

◆ HW_MPU_APL_NP

enum HW_MPU_APL_NP

Privileged or Non-Privileged access.

Attribute to allow an application the privilege of accessing CPU features such as memory, I/O, enable/disable interrupts, setup the NVIC, etc. By system design it can be imperative to restrict an application by defining accordingly the MPU settings for the corresponding region.

Enumerator
HW_MPU_APL_NP_PRIVRW	Privileged code only
HW_MPU_APL_NP_RW	Any privilege level

◆ HW_MPU_ATTR

enum HW_MPU_ATTR

Memory Type.

Attribute regarding the memory type of a particular region. According to ARM CM33 nomenclature two memory types are defined: device memory pertains to a memory-mapped region for a peripheral, while normal memory is instead relevant to CPU use. The following enumerator sums up the two most commonly deployed attribute setups: 0x00 - Device Memory, non-Gathering, non-Re-Ordering, non-Early-Write-Acknowledgement (nGnRnE). 0x44 - Inner Memory normal and non-Cacheable, Outer Memory normal and non-Cacheable.

Enumerator
HW_MPU_ATTR_DEVICE	Device Memory, nGnRnE
HW_MPU_ATTR_NORMAL	Normal memory, Outer non-cacheable, Inner non-cacheable

◆ HW_MPU_ATTR_INDEX

enum HW_MPU_ATTR_INDEX

Memory attributes.

Enumerator
HW_MPU_ATTR_INDEX_0	MPU attribute 0
HW_MPU_ATTR_INDEX_1	MPU attribute 1
HW_MPU_ATTR_INDEX_2	MPU attribute 2
HW_MPU_ATTR_INDEX_3	MPU attribute 3
HW_MPU_ATTR_INDEX_4	MPU attribute 4
HW_MPU_ATTR_INDEX_5	MPU attribute 5
HW_MPU_ATTR_INDEX_6	MPU attribute 6
HW_MPU_ATTR_INDEX_7	MPU attribute 7

◆ HW_MPU_REGION_NUM

enum HW_MPU_REGION_NUM

Region Definitions.

The MPU divides the memory map into a number of eight regions. Each region has a defined memory type and memory attributes that determine the behavior of accesses to the region. A background (or default) region numbered as -1 exists with the same access attributes as the generic memory map, but is accessible from privileged software only.

Enumerator
HW_MPU_REGION_NONE	MPU Protection Omitted
HW_MPU_REGION_0	MPU region 0
HW_MPU_REGION_1	MPU region 1
HW_MPU_REGION_2	MPU region 2
HW_MPU_REGION_3	MPU region 3
HW_MPU_REGION_4	MPU region 4
HW_MPU_REGION_5	MPU region 5
HW_MPU_REGION_6	MPU region 6
HW_MPU_REGION_7	MPU region 7

◆ HW_MPU_SH

enum HW_MPU_SH

Shareability.

Attribute regarding the Shareability status (SH) of a particular region. In our case (ARMv8-M33) the options regarding Shareability are:

         [Non-shareable] - This represents memory accessible only by a single processor or other agent,
         so memory accesses never need to be synchronized with other processors.
         [Inner Shareable] - This represents a shareability domain that can be shared by multiple processors,
         but not necessarily all of the agents in the system. A system might have multiple Inner Shareable
         domains. An operation that affects one Inner Shareable domain does not affect other Inner Shareable
         domains in the system.
         [Outer Shareable] - An outer shareable (OSH) domain re-order is shared by multiple agents and can
         consist of one or more inner shareable domains. An operation that affects an outer shareable domain
         also implicitly affects all inner shareable domains inside it. However, it does not otherwise behave
         as an inner shareable operation.

CAUTION: The value of HW_MPU_SH must ALWAYS be other-than 0x01. A value of 0x01 will lead to UNPREDICTABLE behavior according to ARMv8 MPU documentation. The most common Shareability status is Non-Shareable.

Enumerator
HW_MPU_SH_NS	Non-Shareable
HW_MPU_SH_OS	Outer Shareable
HW_MPU_SH_IS	Inner Shareable

◆ HW_MPU_XN

enum HW_MPU_XN

Executable Region.

Attribute regarding the code execution from a particular region. The XN (eXecute Never) flag must be zero and there must be read access for the privilege level in order to execute code from the region, otherwise a memory manage (MemManage) fault is generated.

Enumerator
HW_MPU_XN_FALSE	Executable region
HW_MPU_XN_TRUE	Execute never region

Function Documentation

◆ hw_mpu_config_region()

void hw_mpu_config_region	(	HW_MPU_REGION_NUM	region_num,
		mpu_region_config *	cfg
	)

Configures an MPU region. Region's start and end addresses will be aligned to 32 byte boundary. The start address is ANDed with 0xFFFFFFE0 whereas the end address is ORed with 0x1F.

The following accesses will generate a hard fault:

An access to an address that matches in more than one region.
An access that does not match all the access conditions for that region.
An access to the background region, depending on the privilege mode and the value of the 'privdefena' parameter when MPU is enabled.

Parameters

[in]	region_num	Region number
[in]	cfg	Region configuration. When cfg is NULL the particular region is disabled.

Note: The regions intended for protection will be rounded to increments of 32 bytes in any case. This is a result of the fact that the 5 low bits of RLAR and RBAR registers are reserved for other purposes. The first two assertions serve as a reminder of that detail.

◆ hw_mpu_disable()

__STATIC_FORCEINLINE void hw_mpu_disable ( void )

Disables the MPU.

◆ hw_mpu_enable()

__STATIC_FORCEINLINE void hw_mpu_enable ( bool privdefena )

Initializes the MPU by disabling its operation during faults, defining the background region privilege access and finally by enabling the actual HW block.

Parameters

[in]

privdefena

Controls (enable/disable) privileged access to the background region.

         When disabled, any access to the background region will cause a memory manage fault.
         When enabled, privileged accesses to the background region are allowed.

         In handler mode, execution is always privileged. In thread mode
         privilege level can be set using the 'nPRIV' field of the control register.
         For manipulating nPRIV, check __set_CONTROL() and __get_CONTROL() CMSIS API calls.
         Hard fault and NMI handlers always operate with MPU disabled, accessing the
         default memory map as normal. The same can be true when FAULTMASK is set to 1,
         effectively masking Hard Fault exceptions by raising the current priority level to -1.
         FAULTMASK can only be set in privileged mode except from within NMI and HardFault
         Handlers (in which cases lockup state will be entered).

◆ hw_mpu_fetch_region_configuration()

void hw_mpu_fetch_region_configuration	(	HW_MPU_REGION_NUM	region_num,
		mpu_region_config *	cfg
	)

Fetches the configuration of an MPU region.

Parameters

[in]	region_num	Region number.
[in]	*cfg	Region configuration.

◆ hw_mpu_hardfault_nmi_handlers_enable()

__STATIC_FORCEINLINE void hw_mpu_hardfault_nmi_handlers_enable ( bool hfnmiena )

Enables/Disables the operation of MPU during hard fault, NMI, and FAULTMASK handlers.

Parameters

[in]

hfnmiena

Controls (enable/disable) operation of MPU during HardFault and NMI handlers.

         When disabled, MPU is disabled during HardFault and NMI handlers, regardless of the
         value of the ENABLE bit.
         When enabled, the MPU is enabled during HardFault and NMI handlers.

◆ hw_mpu_is_enabled()

__STATIC_FORCEINLINE bool hw_mpu_is_enabled ( void )

Checks if MPU is enabled.

Returns: true if enabled, false otherwise

◆ hw_mpu_privileged_background_access_enable()

__STATIC_FORCEINLINE void hw_mpu_privileged_background_access_enable ( bool privdefena )

Enables/Disables Privileged Background Access.

Parameters

[in]

privdefena

Controls (enable/disable) privileged access to the background region.

         When disabled, any access to the background region will cause a memory manage fault.
         When enabled, privileged accesses to the background region are allowed.

         In handler mode, execution is always privileged. In thread mode
         privilege level can be set using the 'nPRIV' field of the control register.
         For manipulating nPRIV, check __set_CONTROL() and __get_CONTROL() CMSIS API calls.
         Hard fault and NMI handlers always operate with MPU disabled, accessing the
         default memory map as normal. The same can be true when FAULTMASK is set to 1,
         effectively masking Hard Fault exceptions by raising the current priority level to -1.
         FAULTMASK can only be set in privileged mode except from within NMI and HardFault
         Handlers (in which cases lockup state will be entered).

◆ hw_mpu_set_attribute_indirection()

void hw_mpu_set_attribute_indirection	(	HW_MPU_REGION_NUM	region_num,
		HW_MPU_ATTR_INDEX	attr
	)

Configures an MPU attribute indirection.

Parameters

[in]	region_num	Region number.
[in]	attr	The region number selects one from the available memory attributes.

Files

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ HW_MPU_AP

◆ HW_MPU_APH_RO

◆ HW_MPU_APL_NP

◆ HW_MPU_ATTR

◆ HW_MPU_ATTR_INDEX

◆ HW_MPU_REGION_NUM

◆ HW_MPU_SH

◆ HW_MPU_XN

Function Documentation

◆ hw_mpu_config_region()

◆ hw_mpu_disable()

◆ hw_mpu_enable()

◆ hw_mpu_fetch_region_configuration()

◆ hw_mpu_hardfault_nmi_handlers_enable()

◆ hw_mpu_is_enabled()

◆ hw_mpu_privileged_background_access_enable()

◆ hw_mpu_set_attribute_indirection()