Memory Protection and Attribute Manager (MPAM)#

Overview#

The Memory Protection and Attribute Manager (MPAM) is a software module that provides an interface to configure memory protection and attributes for different regions of memory. It is designed to work with the hardware memory protection features of the device, such as the ARM Cortex-M MPU.

The MPAM allows you to define memory regions with specific attributes, such as non-cacheable, non-shareable, non-executable, and read-only. It also provides functions to configure or disable these regions, as well as to allocate/free memory for MPA region handles.

The MPAM supports the following operations:

Allocate memory for an MPA region handle using sl_mpa_manager_alloc_region_handle.
Configure a memory region with a specific attribute using sl_mpa_manager_configure_region.
Disable a memory region using sl_mpa_manager_disable_region.
Free the memory allocated for an MPA region handle using sl_mpa_manager_free_region_handle.

Initialization#

The MPAM is initialized using the sl_mpa_manager_init function. This function must be called before any other MPAM functions can be used.

Usage#

The following code snippet shows how to allocate memory for an MPA region handle and configure a memory region with specific attributes:

sl_status_t status = SL_STATUS_OK;
sl_mpa_manager_region_t* handle = NULL;

// Allocate memory for an MPA region handle
status = sl_mpa_manager_alloc_region_handle(&handle);
if (status != SL_STATUS_OK) {
  // Handle the error.
}

// Configure a memory region with specific attributes
status = sl_mpa_manager_configure_region(handle,
                                         (void*)0x20000000,
                                         0x1000,
                                         SL_MPA_MANAGER_ATTRIBUTE_NON_CACHEABLE);
if (status != SL_STATUS_OK) {
  // Handle the error.
}

Disabling a memory region will remove the configuration from the hardware and free the resources associated with the region handle. Assuming a region was configured as in the previous code snippet, the following code snippet shows how to disable the same MPA region and free the MPA region handle:

// Disable the MPA region
status = sl_mpa_manager_disable_region(handle);
if (status != SL_STATUS_OK) {
  // Handle the error.
}

// Free the memory allocated for the MPA region handle
status = sl_mpa_manager_free_region_handle(handle);
if (status != SL_STATUS_OK) {
  // Handle the error.
}

Architecture Support#

The Memory Protection and Attribute Manager supports the following architecture(s):

ARMv8m

ARMv8m Limitation#

For ARMv8m devices, MPA regions can only be defined for memory addresses that are of the Normal memory type in the ARMv8m system memory map. These Normal memory type address spaces are as follows:


Region	Address Space
CODE	0x00000000 to 0x1FFFFFFF
SRAM	0x20000000 to 0x3FFFFFFF
RAM	0x60000000 to 0x7FFFFFFF
RAM	0x80000000 to 0x9FFFFFFF

More information about the ARMv8m system memory map can be found in the ARMv8m Architecture Reference Manual.

Modules#

sl_mpa_manager_region_t

Enumerations#

enum

sl_mpa_manager_attribute_t {

SL_MPA_MANAGER_ATTRIBUTE_NON_CACHEABLE = 0

SL_MPA_MANAGER_ATTRIBUTE_NON_CACHEABLE_UNIFIED_CACHE

SL_MPA_MANAGER_ATTRIBUTE_NON_SHAREABLE

SL_MPA_MANAGER_ATTRIBUTE_NON_EXECUTABLE

SL_MPA_MANAGER_ATTRIBUTE_READ_ONLY

SL_MPA_MANAGER_ATTRIBUTE_MAX

}

MPA Manager region attribute type.

Functions#

void

sl_mpa_manager_init(void)

Initializes the MPA Manager.

sl_status_t

sl_mpa_manager_configure_region(sl_mpa_manager_region_t *handle, void *base_address, size_t size, sl_mpa_manager_attribute_t attribute)

Configure an MPA region.

sl_status_t

sl_mpa_manager_disable_region(sl_mpa_manager_region_t *handle)

Disable an MPA region.

size_t

sl_mpa_manager_get_region_handle_size(void)

Get the size of the MPA region data structure.

sl_status_t

sl_mpa_manager_alloc_region_handle(sl_mpa_manager_region_t **handle)

Allocate memory for an MPA region on the heap.

sl_status_t

sl_mpa_manager_free_region_handle(sl_mpa_manager_region_t *handle)

Free the MPA region memory allocated.

Enumeration Documentation#

sl_mpa_manager_attribute_t#

sl_mpa_manager_attribute_t

MPA Manager region attribute type.

Enumerator
SL_MPA_MANAGER_ATTRIBUTE_NON_CACHEABLE	Region is non-cacheable.
SL_MPA_MANAGER_ATTRIBUTE_NON_CACHEABLE_UNIFIED_CACHE	Region is non-cacheable only when the device has a unified cache.
SL_MPA_MANAGER_ATTRIBUTE_NON_SHAREABLE	Region is shareable.
SL_MPA_MANAGER_ATTRIBUTE_NON_EXECUTABLE	Region is non-executable.
SL_MPA_MANAGER_ATTRIBUTE_READ_ONLY	Region is read-only.
SL_MPA_MANAGER_ATTRIBUTE_MAX

Function Documentation#

sl_mpa_manager_init#

void sl_mpa_manager_init (void )

Initializes the MPA Manager.

Parameters

Type	Direction	Argument Name	Description
void	N/A

This function intializes the MPA manager. By default, the default memory map attributes for the target hardware applies.

sl_mpa_manager_configure_region#

sl_status_t sl_mpa_manager_configure_region (sl_mpa_manager_region_t * handle, void * base_address, size_t size, sl_mpa_manager_attribute_t attribute)

Configure an MPA region.

Parameters

Type	Direction	Argument Name	Description
sl_mpa_manager_region_t *	[in]	handle	The MPA region handle.
void *	[in]	base_address	The base address of the memory region (Multiple of 32 bytes).
size_t	[in]	size	The size of the memory region, in bytes (Multiple of 32 bytes).
sl_mpa_manager_attribute_t	[in]	attribute	The attribute to be applied to the memory region (Cannot be OR-ed).

This function will attempt to configure an MPA region in the MPA Manager. Doing this triggers a re-configuration of the hardware, and if the hardware cannot be re-configured, then the MPA region will not be configured in the MPA Manager. Whenever this function is not successful, the state of the program will remain as it was before the function was called.

This function can be used to add a new, or modify an existing MPA region for which the caller has a handle, provided that the modification can be accomodated by the hardware.

Returns

SL_STATUS_OK:
- the MPA region is configured successfully.
SL_STATUS_INVALID_PARAMETER:
- the MPA region handle is NULL.
- the base_address is not a multiple of 32 bytes.
- the size is not a multiple of 32 bytes.
- the attribute is not valid.
SL_STATUS_FAIL:
- the hardware is not able to be re-configured with the MPA region provided.

Note

If base_address or size parameters are both not a multiple of 32 bytes, the caller of this function must round them to the nearest 32 bytes.
The attribute parameter is an enum type which cannot be OR-ed, therefore, in order to apply multiple attributes to a memory range, individual MPA regions must be configured.

sl_mpa_manager_disable_region#

sl_status_t sl_mpa_manager_disable_region (sl_mpa_manager_region_t * handle)

Disable an MPA region.

Parameters

Type	Direction	Argument Name	Description
sl_mpa_manager_region_t *	[in]	handle	The MPA region handle.

This function will attempt to disable an MPA region in the MPA Manager. Doing this triggers a re-configuration of the hardware, and if the hardware cannot be re-configured, then the MPA region will not be disabled in the MPA Manager. Whenever this function is not successful, the state of the program will remain as it was before the function was called.

Returns

SL_STATUS_OK:
- the MPA region is disabled successfully.
SL_INVALID_PARAMETER:
- the MPA region handle is NULL.
SL_STATUS_FAIL:
- the hardware is not able to be re-configured after disabling the MPA region.

sl_mpa_manager_get_region_handle_size#

size_t sl_mpa_manager_get_region_handle_size (void )

Get the size of the MPA region data structure.

Parameters

Type	Direction	Argument Name	Description
void	N/A

This function is used to get the data structure size of an MPA region which can be used for custom memory allocation of an MPA region's data.

Returns

The size of the MPA region data structure.

sl_mpa_manager_alloc_region_handle#

sl_status_t sl_mpa_manager_alloc_region_handle (sl_mpa_manager_region_t ** handle)

Allocate memory for an MPA region on the heap.

Parameters

Type	Direction	Argument Name	Description
sl_mpa_manager_region_t **	[out]	handle	Pointer to the handle of the allocated MPA region. NULL if the allocation fails.

This function allocates memory for an MPA region on the heap using the memory manager, and then returns a handle for that MPA region.

Returns

SL_STATUS_OK:
- the MPA region memory is allocated successfully.
SL_STATUS_NULL_POINTER:
- the pointer to the handle is a NULL pointer.
SL_STATUS_ALLOCATION_FAILED:
- the failed to allocate memory for the region.

sl_mpa_manager_free_region_handle#

sl_status_t sl_mpa_manager_free_region_handle (sl_mpa_manager_region_t * handle)

Free the MPA region memory allocated.

Parameters

Type	Direction	Argument Name	Description
sl_mpa_manager_region_t *	[in]	handle	Pointer to the handle of an MPA region.

This function frees the MPA region handle. If the MPA region is not disabled, the MPA region handle will not be freed.

Returns

SL_STATUS_OK:
- the MPA region's data was freed successfully.
SL_INVALID_PARAMETER:
- the MPA region handle is NULL.
SL_STATUS_INVALID_STATE:
- the MPA region is currently configured and must be disabled before freeing it.
SL_STATUS_FAIL:
- the MPA region's data was not freed successfully.