Updated Jul 2025

vTaskAllocateMPURegions

[FreeRTOS-MPU Specific]

task. h

1void vTaskAllocateMPURegions(
2 TaskHandle_t xTaskToModify,
3 const MemoryRegion_t * const xRegions );

Memory regions are assigned to a restricted task when the task is created using a call to

xTaskCreateRestricted()
. The regions can then be modified or redefined at run time using
vTaskAllocateMPURegions()
.

vTaskAllocateMPURegions()
is intended for use with FreeRTOS-MPU, the demo applications for which contain an example of
vTaskAllocateMPURegions()
being used.

Parameters:

  • xTask

    The handle of the task being updated.

  • xRegions

    A pointer to an array of

    MemoryRegion_t
    structures, each of which contains a single new memory region definitions. The array should be dimensioned using the constant
    portNUM_CONFIGURABLE_REGIONS
    , which on the ARM Cortex-M3 is set to 3.

MemoryRegion_t
is defined in task.h as:

1typedef struct xMEMORY_REGION
2{
3 void *pvBaseAddress;
4 unsigned long ulLengthInBytes;
5 unsigned long ulParameters;
6} MemoryRegion_t;

The

pvBaseAddress
and
ulLengthInBytes
members are self explanatory as the start of the memory region and the length of the memory region respectively. It is important to note that MPU regions must meet a number of constraints - in particular, the size and alignment of each region must both be equal to the same power of two value.

ulParameters
defines how the task is permitted to access the memory region and can take the bitwise OR of the following values:

1 portMPU_REGION_READ_WRITE
2 portMPU_REGION_PRIVILEGED_READ_ONLY
3 portMPU_REGION_READ_ONLY
4 portMPU_REGION_PRIVILEGED_READ_WRITE
5 portMPU_REGION_CACHEABLE_BUFFERABLE
6 portMPU_REGION_EXECUTE_NEVER

Example usage (please refer to the FreeRTOS-MPU demo applications for a much more complete and comprehensive example):

1/* Define an array that the task will both read from and write to. Make sure
2 the size and alignment are appropriate for an MPU region (note this uses GCC
3 syntax). */
4static unsigned char ucOneKByte[ 1024 ] __attribute__((align( 1024 )));
5
6/* Define an array of MemoryRegion\_t structures that configures an MPU region
7 allowing read/write access for 1024 bytes starting at the beginning of the
8 ucOneKByte array. The other two of the maximum 3 definable regions are
9 unused so set to zero. */
10static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
11{
12 /* Base address Length Parameters */
13 { ucOneKByte, 1024, portMPU_REGION_READ_WRITE },
14 { 0, 0, 0 },
15 { 0, 0, 0 }
16};
17
18void vATask( void *pvParameters )
19{
20 /* This task was created such that it has access to certain regions of
21 memory as defined by the MPU configuration. At some point it is
22 desired that these MPU regions are replaced with that defined in the
23 xAltRegions const struct above. Use a call to vTaskAllocateMPURegions()
24 for this purpose. NULL is used as the task handle to indicate that this
25 function should modify the MPU regions of the calling task. */
26 vTaskAllocateMPURegions( NULL, xAltRegions );
27
28 /* Now the task can continue its function, but from this point on can only
29 access its stack and the ucOneKByte array (unless any other statically
30 defined or shared regions have been declared elsewhere). */
31}