MPU

This section describes the programming interfaces of Memory Protection Unit (MPU) HAL driver. More...

Overview

This section describes the programming interfaces of Memory Protection Unit (MPU) HAL driver.

The MPU is an optional component in ARMv7-M architecture, that provides control of access rights on physical addresses. The processor supports a standard ARMv7 Protected Memory System Architecture model. The MPU divides the memory map into a number of regions, and defines the location, size, access permissions and memory attributes of each region. The Cortex-M4 MPU defines eight separate memory regions as well as a background region. The Cortex-M4 MPU memory map is unified. This means instruction accesses and data accesses have the same region settings. The MPU provides full support for:

• Protection regions.
  • Independent attribute settings for each region.
• Overlapping protection regions, with ascending region priority:
  • 7 = highest priority
  • 0 = lowest priority
• Access permissions.
• Exporting memory attributes to the system.
  

MPU mismatches and permission violations invoke the programmable-priority MemManage fault handler.
You can use the MPU to:

• Enforce privilege rules.
• Separate processes.
• Enforce access rules.

Terms and acronyms

The following provides descriptions to the terms commonly used in the MPU driver and how to use its various functions.

Terms	Details
MPU	Memory Protection Unit. For more information, please refer to ARMv7-M Architecture Reference Manual.

Supported features

The MPU HAL driver enables configuration of location, size and access permissions for each region. The configuration of memory attributes (TEX, C, B bits field of the Region Attribute and Size Register) is not supported. Call the MPU APIs to configure the MPU, as shown below:

• Configure each region for different access permissions.
  Call hal_mpu_region_configure(), to configure the specified region. The first parameter is of hal_mpu_region_t type, to indicate which region is to be configured. The second parameter is of hal_mpu_region_config_t type, and defines the location, size and access permissions of the region. The sub region feature of MPU is also supported by defining mpu_subregion_mask field of type hal_mpu_region_config_t.
• Enable the MPU feature inside the MCU.
  To enable the MPU settings for the configured region(s), user has to follow these two steps:
  • Step1: Call hal_mpu_region_enable() to enable the MPU region(s).
  • Step2: Call hal_mpu_enable() to enable the MPU function.
    
  Note, that at least one region of the memory map must be enabled for the system to operate when hal_mpu_enable() is called, unless the PRIVDEFENA field in the structure hal_mpu_config_t is set to TRUE. This structure is a parameter in the MPU initialization function hal_mpu_init(). If the PRIVDEFENA field is set to TRUE and no regions are enabled, then only privileged software can operate. If the PRIVDEFENA is set to TRUE and the MPU is enable as well:
  • Any access by privileged software that does not address an enabled memory region behaves as defined by the default memory map.
  • Any access by unprivileged software that does not address an enabled memory region causes a MemManage fault.
    
  When hal_mpu_disable() is called and PRIVDEFENA field is set to FALSE, the system uses the default memory map. This has the same memory attributes as if the MPU is not implemented. The default memory map applies to accesses from both privileged and unprivileged software.
  When the MPU is enabled, accesses to the System Control Space and vector table are always permitted. Other areas are accessible based on regions and whether PRIVDEFENA is set to TRUE.
  
  • Unless HFNMIENA is set to TRUE, the MPU is not enabled when the processor is executing an exception handler with priority -1 or -2. These priorities are only possible when handling a hard fault or NMI (Non Maskable Interrupt) exception, or when FAULTMASK is enabled. Setting the HFNMIENA field to TRUE enables the MPU when operating with these two priorities.
  • User should make sure that the unused region(s) is (are) disabled when the MPU is enabled.
• Set the PRIVDEFENA and HFNMIENA features of the MPU.
  User can set the PRIVDEFENA and HFNMIENA features of the MPU, by calling hal_mpu_init(). For more information about PRIVDEFENA and HFNMIENA, please refer to ARMv7-M Architecture Reference Manual.

How to use this driver

The MPU HAL driver APIs enable the user to perform the following.

• Set location, size and access permissions for each region.
  • As described above in the section Supported features, user can accomplish this by calling hal_mpu_region_configure(). The sample code is shown below:
  • Sample code:

    hal_mpu_region_t region = HAL_MPU_REGION_0;
    hal_mpu_region_config_t region_config;
    
    memset(region_config, 0, sizeof(hal_mpu_region_config_t));//Note, call memset() to make sure all memory regions are set to 0.
    region_config.mpu_region_address = 0x10000000;//The start address of the region that is configured.
    region_config.mpu_region_size = HAL_MPU_REGION_SIZE_1KB;//The size of the region.
    region_config.mpu_region_access_permission = HAL_MPU_FULL_ACCESS;//Access permission is full access.
    region_config.mpu_subregion_mask = 0x00;//Unmask all sub regions.
    region_config.mpu_xn = FALSE;//Enables the instruction access.
    
    hal_mpu_region_configure(region, &region_config);

• Enable MPU function inside the MCU.
  First call hal_mpu_region_enable() to enable the region(s), then hal_mpu_enable(), to enable the MPU. The sample code is shown below:
  • Sample code:

    hal_mpu_region_t region = HAL_MPU_REGION_0;
    
    hal_mpu_region_enable(region);//Enables the region.
    hal_mpu_enable();//Enables the MPU.

Functions
hal_mpu_status_t	hal_mpu_init (const hal_mpu_config_t *mpu_config)
	MPU initialization function. More...
hal_mpu_status_t	hal_mpu_deinit (void)
	MPU deinitialization function. More...
hal_mpu_status_t	hal_mpu_enable (void)
	MPU enable function. More...
hal_mpu_status_t	hal_mpu_disable (void)
	MPU disable function. More...
hal_mpu_status_t	hal_mpu_region_enable (hal_mpu_region_t region)
	MPU region enable function. More...
hal_mpu_status_t	hal_mpu_region_disable (hal_mpu_region_t region)
	MPU region disable function. More...
hal_mpu_status_t	hal_mpu_region_configure (hal_mpu_region_t region, const hal_mpu_region_config_t *region_config)
	MPU region configuration function. More...

Modules
	Enum
	Struct

Function Documentation

hal_mpu_status_t hal_mpu_deinit

(

void

)

MPU deinitialization function.

This function resets the MPU registers to their default values.

Returns

HAL_MPU_STATUS_OK, MPU is successfully deinitialized.

hal_mpu_status_t hal_mpu_disable

(

void

)

MPU disable function.

Disables the MPU settings.

See also

hal_mpu_enable().

Returns

HAL_MPU_STATUS_OK, MPU is successfully disabled.

hal_mpu_status_t hal_mpu_enable

(

void

)

MPU enable function.

Enables the MPU settings during a memory access.

See also

hal_mpu_disable().

Returns

HAL_MPU_STATUS_OK, MPU is successfully enabled .

hal_mpu_status_t hal_mpu_init

(

const hal_mpu_config_t *

mpu_config

)

MPU initialization function.

Parameters

[in]

mpu_config

is the configuration information for MPU.

Returns

HAL_MPU_STATUS_OK, MPU is successfully initialized.
HAL_MPU_STATUS_INVALID_PARAMETER, mpu_config is NULL.
HAL_MPU_STATUS_ERROR_BUSY, MPU is busy.

hal_mpu_status_t hal_mpu_region_configure	(	hal_mpu_region_t	region,
		const hal_mpu_region_config_t *	region_config
	)

MPU region configuration function.

Parameters

[in]	region	is the region that is configured.
[in]	region_config	is the configuration information of the region.

Returns

HAL_MPU_STATUS_OK, MPU region is successfully configured.
HAL_MPU_STATUS_INVALID_PARAMETER, region_config is NULL.
HAL_MPU_STATUS_ERROR_REGION, the region is invalid.
HAL_MPU_STATUS_ERROR_REGION_SIZE, the region size is invalid.
HAL_MPU_STATUS_ERROR_REGION_ADDRESS, the region address is invalid.

hal_mpu_status_t hal_mpu_region_disable

(

hal_mpu_region_t

region

)

MPU region disable function.

Disables the specified region, when this function is called, the settings of corresponding region are disabled even if the hal_mpu_enable() function is called.

See also

hal_mpu_disable().

Parameters

[in]

region

is the region that is disabled, this parameter can only be a value of type hal_mpu_region_t.

Returns

HAL_MPU_STATUS_OK, MPU region is successfully disabled.
HAL_MPU_STATUS_ERROR_REGION, the region is invalid.

hal_mpu_status_t hal_mpu_region_enable

(

hal_mpu_region_t

region

)

MPU region enable function.

Enables the specified region, when the hal_mpu_enable() is called, the settings of the corresponding region take effect.

See also

hal_mpu_enable().

Parameters

[in]

region

is the region that is enabled, this parameter can only be a value of type hal_mpu_region_t.

Returns

HAL_MPU_STATUS_OK, MPU region is successfully enabled.
HAL_MPU_STATUS_ERROR_REGION, the region is invalid.