Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
xTaskCreateRestricted

task.

h

 portBASE_TYPE xTaskCreateRestricted( xTaskParameters *pxTaskDefinition, xTaskHandle *pxCreatedTask );

xTaskCreateRestricted() should only be used in systems that include an MPU implementation.

Create a new task and add it to the list of tasks that are ready to run. The function parameters define the memory regions and associated access permissions allocated to the task.

Parameters
pxTaskDefinitionPointer to a structure that contains a member for each of the normal xTaskCreate() parameters (see the xTaskCreate() API documentation) plus an optional stack buffer and the memory region definitions.
pxCreatedTaskUsed 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 errors. h

Example usage:

Create an xTaskParameters structure that defines the task to be created.
static const xTaskParameters xCheckTaskParameters =
{
    vATask,     // pvTaskCode - the function that implements the task.
    "ATask",    // pcName - just a text name for the task to assist debugging.
    100,        // usStackDepth - the stack size DEFINED IN WORDS.
    NULL,       // pvParameters - passed into the task function as the function parameters.
    ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
    cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
xRegions - Allocate up to three separate memory regions for access by
the task, with appropriate access permissions.  Different processors have
different memory alignment requirements - refer to the FreeRTOS documentation
for full information.
    {
Base address                    Length  Parameters
        { cReadWriteArray,              32,     portMPU_REGION_READ_WRITE },
        { cReadOnlyArray,               32,     portMPU_REGION_READ_ONLY },
        { cPrivilegedOnlyAccessArray,   128,    portMPU_REGION_PRIVILEGED_READ_WRITE }
    }
};
int main( void )
{
xTaskHandle xHandle;
Create a task from the const structure defined above.  The task handle
is requested (the second parameter is not NULL) but in this case just for
demonstration purposes as its not actually used.
    xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
Start the scheduler.
    vTaskStartScheduler();
Will only get here if there was insufficient memory to create the idle
task.
    for( ;; );
}
   

h

 void vTaskAllocateMPURegions( xTaskHandle xTask, const xMemoryRegion * const pxRegions );

Memory regions are assigned to a restricted task when the task is created by a call to xTaskCreateRestricted(). These regions can be redefined using vTaskAllocateMPURegions().

Parameters
xTaskThe handle of the task being updated.
xRegionsA pointer to an xMemoryRegion structure that contains the new memory region definitions.

Example usage:

Define an array of xMemoryRegion structures that configures an MPU region
allowing read/write access for 1024 bytes starting at the beginning of the
ucOneKByte array.  The other two of the maximum 3 definable regions are
unused so set to zero.
static const xMemoryRegion xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
{
Base address        Length      Parameters
    { ucOneKByte,       1024,       portMPU_REGION_READ_WRITE },
    { 0,                0,          0 },
    { 0,                0,          0 }
};
void vATask( void *pvParameters )
{
This task was created such that it has access to certain regions of
memory as defined by the MPU configuration.  At some point it is
desired that these MPU regions are replaced with that defined in the
xAltRegions const struct above.  Use a call to vTaskAllocateMPURegions()
for this purpose.  NULL is used as the task handle to indicate that this
function should modify the MPU regions of the calling task.
    vTaskAllocateMPURegions( NULL, xAltRegions );
Now the task can continue its function, but from this point on can only
access its stack and the ucOneKByte array (unless any other statically
defined or shared regions have been declared elsewhere).
}
   

h

 BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );

Only available when configSUPPORT_DYNAMIC_ALLOCATION is set to 1.

xTaskCreateRestricted() should only be used in systems that include an MPU implementation.

Create a new task and add it to the list of tasks that are ready to run. The function parameters define the memory regions and associated access permissions allocated to the task.

See xTaskCreateRestrictedStatic() for a version that does not use any dynamic memory allocation.

Parameters
pxTaskDefinitionPointer to a structure that contains a member for each of the normal xTaskCreate() parameters (see the xTaskCreate() API documentation) plus an optional stack buffer and the memory region definitions.
pxCreatedTaskUsed 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

Example usage:

Create an TaskParameters_t structure that defines the task to be created.
static const TaskParameters_t xCheckTaskParameters =
{
    vATask,     // pvTaskCode - the function that implements the task.
    "ATask",    // pcName - just a text name for the task to assist debugging.
    100,        // usStackDepth - the stack size DEFINED IN WORDS.
    NULL,       // pvParameters - passed into the task function as the function parameters.
    ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
    cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
xRegions - Allocate up to three separate memory regions for access by
the task, with appropriate access permissions.  Different processors have
different memory alignment requirements - refer to the FreeRTOS documentation
for full information.
    {
Base address                    Length  Parameters
        { cReadWriteArray,              32,     portMPU_REGION_READ_WRITE },
        { cReadOnlyArray,               32,     portMPU_REGION_READ_ONLY },
        { cPrivilegedOnlyAccessArray,   128,    portMPU_REGION_PRIVILEGED_READ_WRITE }
    }
};
int main( void )
{
TaskHandle_t xHandle;
Create a task from the const structure defined above.  The task handle
is requested (the second parameter is not NULL) but in this case just for
demonstration purposes as its not actually used.
    xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
Start the scheduler.
    vTaskStartScheduler();
Will only get here if there was insufficient memory to create the idle
and/or timer task.
    for( ;; );
}
   

h

 void vTaskAllocateMPURegions( TaskHandle_t xTask, const MemoryRegion_t * const pxRegions );

Memory regions are assigned to a restricted task when the task is created by a call to xTaskCreateRestricted(). These regions can be redefined using vTaskAllocateMPURegions().

Parameters
xTaskThe handle of the task being updated.
xRegionsA pointer to an MemoryRegion_t structure that contains the new memory region definitions.

Example usage:

Define an array of MemoryRegion_t structures that configures an MPU region
allowing read/write access for 1024 bytes starting at the beginning of the
ucOneKByte array.  The other two of the maximum 3 definable regions are
unused so set to zero.
static const MemoryRegion_t xAltRegions[ portNUM_CONFIGURABLE_REGIONS ] =
{
Base address        Length      Parameters
    { ucOneKByte,       1024,       portMPU_REGION_READ_WRITE },
    { 0,                0,          0 },
    { 0,                0,          0 }
};
void vATask( void *pvParameters )
{
This task was created such that it has access to certain regions of
memory as defined by the MPU configuration.  At some point it is
desired that these MPU regions are replaced with that defined in the
xAltRegions const struct above.  Use a call to vTaskAllocateMPURegions()
for this purpose.  NULL is used as the task handle to indicate that this
function should modify the MPU regions of the calling task.
    vTaskAllocateMPURegions( NULL, xAltRegions );
Now the task can continue its function, but from this point on can only
access its stack and the ucOneKByte array (unless any other statically
defined or shared regions have been declared elsewhere).
}
   

h

 BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition, TaskHandle_t *pxCreatedTask );

xTaskCreateRestricted() should only be used in systems that include an MPU implementation.

Create a new task and add it to the list of tasks that are ready to run. The function parameters define the memory regions and associated access permissions allocated to the task.

Parameters
pxTaskDefinitionPointer to a structure that contains a member for each of the normal xTaskCreate() parameters (see the xTaskCreate() API documentation) plus an optional stack buffer and the memory region definitions.
pxCreatedTaskUsed 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

Example usage:

Create an TaskParameters_t structure that defines the task to be created.
static const TaskParameters_t xCheckTaskParameters =
{
    vATask,     // pvTaskCode - the function that implements the task.
    "ATask",    // pcName - just a text name for the task to assist debugging.
    100,        // usStackDepth - the stack size DEFINED IN WORDS.
    NULL,       // pvParameters - passed into the task function as the function parameters.
    ( 1UL | portPRIVILEGE_BIT ),// uxPriority - task priority, set the portPRIVILEGE_BIT if the task should run in a privileged state.
    cStackBuffer,// puxStackBuffer - the buffer to be used as the task stack.
xRegions - Allocate up to three separate memory regions for access by
the task, with appropriate access permissions.  Different processors have
different memory alignment requirements - refer to the FreeRTOS documentation
for full information.
    {
Base address                    Length  Parameters
        { cReadWriteArray,              32,     portMPU_REGION_READ_WRITE },
        { cReadOnlyArray,               32,     portMPU_REGION_READ_ONLY },
        { cPrivilegedOnlyAccessArray,   128,    portMPU_REGION_PRIVILEGED_READ_WRITE }
    }
};
int main( void )
{
TaskHandle_t xHandle;
Create a task from the const structure defined above.  The task handle
is requested (the second parameter is not NULL) but in this case just for
demonstration purposes as its not actually used.
    xTaskCreateRestricted( &xRegTest1Parameters, &xHandle );
Start the scheduler.
    vTaskStartScheduler();
Will only get here if there was insufficient memory to create the idle
and/or timer task.
    for( ;; );
}