xTaskCreateRestrictedStatic

task. h

1BaseType_t xTaskCreateRestrictedStatic( TaskParameters_t *pxTaskDefinition,
2                                        TaskHandle_t *pxCreatedTask );

Create a new Memory Protection Unit (MPU) restricted task and add it to the list of tasks that are ready to run. configSUPPORT_STATIC_ALLOCATION must be set to 1 in

FreeRTOSConfig.h

for this RTOS API function to be available.

Internally, within the FreeRTOS implementation, each task requires two blocks of memory. The first block is used to hold the task's data structures. The second block is used as the task's stack. If a task is created using xTaskCreateRestricted() then the memory for the task's stack is provided by the application writer, and the memory for the task's data structures is automatically allocated from the FreeRTOS heap. If a task is created using xTaskCreateRestrictedStatic() then the application writer must provide the memory for the task's data structures too. xTaskCreateRestrictedStatic() therefore allows a memory protected task to be created without using any dynamic memory allocation.

xTaskCreateRestrictedStatic() is intended for use with FreeRTOS-MPU, the demo applications which contain comprehensive and documented examples of how to use the similar function, xTaskCreateRestricted().

Parameters:

pxTaskDefinition

Pointer to a structure that defines the task. The structure is described on this page.
pxCreatedTask

Used to pass back a handle by which the created task can be referenced.

Returns:

pdPASS if the task was successfully created and added to a ready list, otherwise an error code defined in the file projdefs.h

Tasks that include MPU support require even more parameters to create than those that don't. Passing each parameter to xTaskCreateRestrictedStatic() individually would be unwieldy so instead the structure TaskParameters_t is used to allow the parameters to be configured statically at compile time. The structure is defined in task.h as:

1typedef struct xTASK_PARAMETERS
2{
3    TaskFunction_t pvTaskCode;
4    const char * const pcName;
5    unsigned short usStackDepth;
6    void *pvParameters;
7    UBaseType_t uxPriority;
8    portSTACK_TYPE *puxStackBuffer;
9    MemoryRegion_t xRegions[ portNUM_CONFIGURABLE_REGIONS ];
10    #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
11        StaticTask_t * const pxTaskBuffer;
12    #endif
13} TaskParameters_t;

....where MemoryRegion_t is defined as:

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

Following is a description of each structure member:

pvTaskCode to uxPriority

These members are exactly the same as the parameters of the same name sent to xTaskCreate(). In particular uxPriority is used to set both the priority of the task and the mode in which the task will execute. For example, to create a User mode task at priority 2, simply set uxPriority to 2, to create a Privileged mode task at priority 2 set uxPriority to ( 2 | portPRIVILEGE_BIT ).
puxStackBuffer

Each time a task is switched in, the MPU is dynamically re-configured to define a region that provides the task read and write access to its own stack. MPU regions must meet a number of constraints - in particular, the size and alignment of all such regions must be equal to the same power of two value.

Standard FreeRTOS ports use pvPortMalloc() to allocate a new stack each time a task is created. Providing a pvPortMalloc() implementation that took care of the MPU data alignment requirements would be possible but would also be complex and inefficient in its RAM usage. To remove the need for this complexity FreeRTOS-MPU allows stacks to be declared statically at compile time. This allows the alignment to be managed using compiler extensions and RAM usage efficiency to be managed by the linker. For example, if using GCC, a stack could be declared and correctly aligned using the following code:
```
1char cTaskStack[ 1024 ] __attribute__((aligned(1024));
```
puxStackBuffer would normally be set to the address of the statically declared stack. As an alternative puxStackBuffer can be set to NULL - in which case pvPortMallocAligned() will be called to allocate the task stack and it is the application writer's responsibility to provide an implementation of pvPortMallocAligned() that meets the alignment requirements of the MPU.

xRegions

xRegions is an array of MemoryRegion_t structures, each of which defines a single user definable memory region for use by the task being created. The ARM Cortex-M3 FreeRTOS-MPU port defines portNUM_CONFIGURABLE_REGIONS to be 3.

The pvBaseAddress and ulLengthInBytes members are self explanatory as the start of the memory region and the length of the memory region respectively. 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

pxTaskBuffer

Must point to a variable of type
```
StaticTask_t
```
. The variable will be used to hold the new task's data structures, so it must be persistent (not declared on the stack of a function).

Example usage:

1/* Create an TaskParameters_t structure that defines the task to be created.
2 * The StaticTask_t variable is only included in the structure when
3 * configSUPPORT_STATIC_ALLOCATION is set to 1. The PRIVILEGED_DATA macro can
4 * be used to force the variable into the RTOS kernel's privileged data area. */
5static PRIVILEGED_DATA StaticTask_t xTaskBuffer;
6static const TaskParameters_t xCheckTaskParameters =
7{
8    vATask,     /* pvTaskCode - the function that implements the task. */
9    "ATask",    /* pcName - just a text name for the task to assist debugging. */
10    100,        /* usStackDepth - the stack size DEFINED IN WORDS. */
11    NULL,       /* pvParameters - passed into the task function as the function parameters. */
12    ( 1UL | portPRIVILEGE_BIT ), /* uxPriority - task priority, set the portPRIVILEGE_BIT
13                                    if the task should run in a privileged state. */
14    cStackBuffer, /* puxStackBuffer - the buffer to be used as the task stack. */
15
16    /* xRegions - Allocate up to three separate memory regions for access by
17     * the task, with appropriate access permissions. Different processors have
18     * different memory alignment requirements - refer to the FreeRTOS documentation
19     * for full information. */
20    {
21        /* Base address Length Parameters */
22        { cReadWriteArray,              32,     portMPU_REGION_READ_WRITE },
23        { cReadOnlyArray,               32,     portMPU_REGION_READ_ONLY },
24        { cPrivilegedOnlyAccessArray,   128,    portMPU_REGION_PRIVILEGED_READ_WRITE }
25    }
26
27    &xTaskBuffer; /* Holds the task's data structure. */
28};
29
30 int main( void )
31 {
32 TaskHandle_t xHandle;
33
34    /* Create a task from the const structure defined above. The task handle
35     * is requested (the second parameter is not NULL) but in this case just for
36     * demonstration purposes as its not actually used. */
37    xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
38
39    /* Start the scheduler. */
40    vTaskStartScheduler();
41
42    /* Will only get here if there was insufficient memory to create the idle
43     * and/or timer task. */
44    for( ;; );
45}

xTaskCreateRestrictedStatic

Related links