Group that contains macros & functions for the creation of FreeRTOS Tasks. More...

Collaboration diagram for Task Creation:

Modules
	Task Handles & Enumerations
	Group that contains definitions for task handles.

Functions
BaseType_t	xTaskCreate (TaskFunction_t pxTaskCode, const char const pcName, const uint16_t usStackDepth, void const pvParameters, UBaseType_t uxPriority, TaskHandle_t *const pxCreatedTask) PRIVILEGED_FUNCTION
	Create a new task and add it to the list of tasks that are ready to run. More...

TaskHandle_t	xTaskCreateStatic (TaskFunction_t pxTaskCode, const char const pcName, const uint32_t ulStackDepth, void const pvParameters, UBaseType_t uxPriority, StackType_t const puxStackBuffer, StaticTask_t const pxTaskBuffer) PRIVILEGED_FUNCTION
	Create a new task and add it to the list of tasks that are ready to run. More...

void	vTaskDelete (TaskHandle_t xTaskToDelete) PRIVILEGED_FUNCTION
	Remove a task from the RTOS real time kernel's management. The task being deleted will be removed from all ready, blocked, suspended and event lists. More...

Detailed Description

Group that contains macros & functions for the creation of FreeRTOS Tasks.

Function Documentation

◆ vTaskDelete()

void vTaskDelete ( TaskHandle_t xTaskToDelete )

#include <task.h>

Remove a task from the RTOS real time kernel's management. The task being deleted will be removed from all ready, blocked, suspended and event lists.

Precondition: INCLUDE_vTaskDelete must be defined as 1 for this function to be available. See the configuration section for more information.

Note: The idle task is responsible for freeing the kernel allocated memory from tasks that have been deleted. It is therefore important that the idle task is not starved of microcontroller processing time if your application makes any calls to vTaskDelete (). Memory allocated by the task code is not automatically freed, and should be freed before the task is deleted.

See the demo application file death.c for sample code that utilises vTaskDelete ().

Parameters

xTask The handle of the task to be deleted. Passing NULL will cause the calling task to be deleted.

Example usage:

void vOtherFunction( void )
{
   TaskHandle_t xHandle;
 
    // Create the task, storing the handle.
    xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
 
    // Use the handle to delete the task.
    vTaskDelete( xHandle );
}

◆ xTaskCreate()

BaseType_t xTaskCreate	(	TaskFunction_t	pxTaskCode,
		const char *const	pcName,
		const uint16_t	usStackDepth,
		void *const	pvParameters,
		UBaseType_t	uxPriority,
		TaskHandle_t *const	pxCreatedTask
	)

#include <task.h>

Create a new task and add it to the list of tasks that are ready to run.

Internally, within the FreeRTOS implementation, tasks use two blocks of memory. The first block is used to hold the task's data structures. The second block is used by the task as its stack. If a task is created using xTaskCreate() then both blocks of memory are automatically dynamically allocated inside the xTaskCreate() function. (see http://www.freertos.org/a00111.html).

If a task is created using xTaskCreateStatic() then the application writer must provide the required memory. xTaskCreateStatic() therefore allows a task to be created without using any dynamic memory allocation.

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

xTaskCreate() can only be used to create a task that has unrestricted access to the entire microcontroller memory map. Systems that include MPU support can alternatively create an MPU constrained task using xTaskCreateRestricted().

Parameters

pvTaskCode	Pointer to the task entry function. Tasks must be implemented to never return (i.e. continuous loop).
pcName	A descriptive name for the task. This is mainly used to facilitate debugging. Max length defined by configMAX_TASK_NAME_LEN - default is 16.
usStackDepth	The size of the task stack specified as the number of variables the stack can hold - not the number of bytes. For example, if the stack is 16 bits wide and usStackDepth is defined as 100, 200 bytes will be allocated for stack storage.
pvParameters	Pointer that will be used as the parameter for the task being created.
uxPriority	The priority at which the task should run. Systems that include MPU support can optionally create tasks in a privileged (system) mode by setting bit portPRIVILEGE_BIT of the priority parameter. For example, to create a privileged task at priority 2 the uxPriority parameter should be set to ( 2 \| portPRIVILEGE_BIT ).
pvCreatedTask	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

Example usage:

// Task to be created.
void vTaskCode( void * pvParameters )
{
    for( ;; )
    {
        // Task code goes here.
    }
}
 
// Function that creates a task.
void vOtherFunction( void )
{
static uint8_t ucParameterToPass;
TaskHandle_t xHandle = NULL;
 
    // Create the task, storing the handle.  Note that the passed parameter ucParameterToPass
    // must exist for the lifetime of the task, so in this case is declared static.  If it was just an
    // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time
    // the new task attempts to access it.
    xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );
    configASSERT( xHandle );
 
    // Use the handle to delete the task.
    if( xHandle != NULL )
    {
        vTaskDelete( xHandle );
    }
}

◆ xTaskCreateStatic()

TaskHandle_t xTaskCreateStatic	(	TaskFunction_t	pxTaskCode,
		const char *const	pcName,
		const uint32_t	ulStackDepth,
		void *const	pvParameters,
		UBaseType_t	uxPriority,
		StackType_t *const	puxStackBuffer,
		StaticTask_t *const	pxTaskBuffer
	)

#include <task.h>

Create a new task and add it to the list of tasks that are ready to run.

Internally, within the FreeRTOS implementation, tasks use two blocks of memory. The first block is used to hold the task's data structures. The second block is used by the task as its stack. If a task is created using xTaskCreate() then both blocks of memory are automatically dynamically allocated inside the xTaskCreate() function. (see http://www.freertos.org/a00111.html). If a task is created using xTaskCreateStatic() then the application writer must provide the required memory. xTaskCreateStatic() therefore allows a task to be created without using any dynamic memory allocation.

Parameters

pvTaskCode	Pointer to the task entry function. Tasks must be implemented to never return (i.e. continuous loop).
pcName	A descriptive name for the task. This is mainly used to facilitate debugging. The maximum length of the string is defined by configMAX_TASK_NAME_LEN in FreeRTOSConfig.h.
ulStackDepth	The size of the task stack specified as the number of variables the stack can hold - not the number of bytes. For example, if the stack is 32-bits wide and `ulStackDepth` is defined as 100 then 400 bytes will be allocated for stack storage.
pvParameters	Pointer that will be used as the parameter for the task being created.
uxPriority	The priority at which the task will run.
pxStackBuffer	Must point to a StackType_t array that has at least `ulStackDepth` indexes - the array will then be used as the task's stack, removing the need for the stack to be allocated dynamically.
pxTaskBuffer	Must point to a variable of type StaticTask_t, which will then be used to hold the task's data structures, removing the need for the memory to be allocated dynamically.

Returns: If neither pxStackBuffer or pxTaskBuffer are NULL, then the task will be created and pdPASS is returned. If either pxStackBuffer or pxTaskBuffer are NULL then the task will not be created and errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned.

Example usage:

// Dimensions the buffer that the task being created will use as its stack.
// NOTE:  This is the number of words the stack will hold, not the number of
// bytes.  For example, if each stack item is 32-bits, and this is set to 100,
// then 400 bytes (100 * 32-bits) will be allocated.
#define STACK_SIZE 200
 
// Structure that will hold the TCB of the task being created.
StaticTask_t xTaskBuffer;
 
// Buffer that the task being created will use as its stack.  Note this is
// an array of StackType_t variables.  The size of StackType_t is dependent on
// the RTOS port.
StackType_t xStack[ STACK_SIZE ];
 
// Function that implements the task being created.
void vTaskCode( void * pvParameters )
{
    // The parameter value is expected to be 1 as 1 is passed in the
    // pvParameters value in the call to xTaskCreateStatic().
    configASSERT( ( uint32_t ) pvParameters == 1UL );
 
    for( ;; )
    {
        // Task code goes here.
    }
}
 
// Function that creates a task.
void vOtherFunction( void )
{
    TaskHandle_t xHandle = NULL;
 
    // Create the task without using any dynamic memory allocation.
    xHandle = xTaskCreateStatic(
                  vTaskCode,       // Function that implements the task.
                  "NAME",          // Text name for the task.
                  STACK_SIZE,      // Stack size in words, not bytes.
                  ( void * ) 1,    // Parameter passed into the task.
                  tskIDLE_PRIORITY,// Priority at which the task is created.
                  xStack,          // Array to use as the task's stack.
                  &xTaskBuffer );  // Variable to hold the task's data structure.
 
    // puxStackBuffer and pxTaskBuffer were not NULL, so the task will have
    // been created, and xHandle will be the task's handle.  Use the handle
    // to suspend the task.
    vTaskSuspend( xHandle );
}

Modules

Functions

Detailed Description

Function Documentation

◆ vTaskDelete()

◆ xTaskCreate()

◆ xTaskCreateStatic()