// task.h
BaseType_t xTaskCreate( TaskFunction_t pvTaskCode,
const char * const pcName,
const configSTACK_DEPTH_TYPE uxStackDepth,
void *pvParameters,
UBaseType_t uxPriority,
TaskHandle_t *pxCreatedTask
)
Create a new task and add it to the list of tasks that are ready to run.
configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h, or left undefined (in which case it will default to 1), for this RTOS API function to be available.
Each task requires RAM that is used to hold the task state, and used by the task as its stack. If a task is created using xTaskCreate() then the required RAM is automatically allocated from the FreeRTOS heap. If a task is created using xTaskCreateStatic() then the RAM is provided by the application writer, so it can be statically allocated at compile time.
If you are using FreeRTOS-MPU then we recommend that you use xTaskCreateRestricted() instead of xTaskCreate().
| parameter | Definition |
|---|---|
| pvTaskCode | Pointer to the task entry function (just the name of the function that implements the task, see the example below). Tasks are normally implemented as an infinite loop; the function which implements the task must never attempt to return or exit. Tasks can, however, delete themselves. |
| pcName | A descriptive name for the task. This is mainly used to facilitate debugging, but can also be used to obtain a task handle. The maximum length of a task’s name is defined by configMAX_TASK_NAME_LEN in FreeRTOSConfig.h. |
| uxStackDepth | The number of words (not bytes!) to allocate for use as the task’s stack. For example, if the stack is 16-bits wide and uxStackDepth is 100, then 200 bytes will be allocated for use as the task’s stack. As another example, if the stack is 32-bits wide and uxStackDepth is 400 then 1600 bytes will be allocated for use as the task’s stack. The stack depth multiplied by the stack width must not exceed the maximum value that can be contained in a variable of type size_t. See the FAQ How big should the stack be?. |
| pvParameters | A value that is passed as the paramater to the created task. If pvParameters is set to the address of a variable then the variable must still exist when the created task executes - so it is not valid to pass the address of a stack variable. |
| uxPriority | The priority at which the created task will execute. Systems that include MPU support can optionally create a task in a privileged (system) mode by setting the bit portPRIVILEGE_BIT in uxPriority. For example, to create a privileged task at priority 2 set uxPriority to ( 2 portPRIVILEGE_BIT ). Priorities are asserted to be less than configMAX_PRIORITIES. If configASSERT is undefined, priorities are silently capped at (configMAX_PRIORITIES - 1). |
| pxCreatedTask | Used to pass a handle to the created task out of the xTaskCreate() function. pxCreatedTask is optional and can be set to NULL. |
Returns
If the task was created successfully then pdPASS is returned.
Otherwise errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY is returned.
Example
void vTaskCode( void * pvParameters )
{
configASSERT( ( ( uint32_t ) pvParameters ) == 1);
// some code
}
void vOtherFunction( void )
{
BaseType_t xReturned;
TaskHandle_t xHandle = NULL;
xReturned = xTaskCreate(
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.
&xHandle ); // Used to pass out the created task's handle.
if ( xReturned == pdPASS )
{
/* The task was created. Use the task's handle to delete the task. */
vTaskDelete( xHandle );
}
}
// task.h
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 );
Create a new 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.
Each task requires RAM that is used to hold the task state, and used by the task as its stack. If a task is created using xTaskCreate() then the required RAM is automatically allocated from the FreeRTOS heap. If a task is created using xTaskCreateStatic() then the RAM is provided by the application writer, which results in a greater number of parameters, but allows the RAM to be statically allocated at compile time.
If you are using FreeRTOS-MPU then we recommend you use xTaskCreateRestricted() instead of xTaskCreateStatic().
| parameter | Definition |
|---|---|
| pvTaskCode | Pointer to the task entry function (just the name of the function that implements the task, see the example below). Tasks are normally implemented as an infinite loop; the function which implements the task must never attempt to return or exit. Tasks can, however, delete themselves. |
| pcName | A descriptive name for the task. This is mainly used to facilitate debugging, but can also be used to obtain a task handle. The maximum length of a task’s name is defined by configMAX_TASK_NAME_LEN in FreeRTOSConfig.h. |
| uxStackDepth | The number of words (not bytes!) to allocate for use as the task’s stack. For example, if the stack is 16-bits wide and uxStackDepth is 100, then 200 bytes will be allocated for use as the task’s stack. As another example, if the stack is 32-bits wide and uxStackDepth is 400 then 1600 bytes will be allocated for use as the task’s stack. The stack depth multiplied by the stack width must not exceed the maximum value that can be contained in a variable of type size_t. See the FAQ How big should the stack be?. |
| pvParameters | A value that is passed as the paramater to the created task. If pvParameters is set to the address of a variable then the variable must still exist when the created task executes - so it is not valid to pass the address of a stack variable. |
| uxPriority | The priority at which the created task will execute. Systems that include MPU support can optionally create a task in a privileged (system) mode by setting the bit portPRIVILEGE_BIT in uxPriority. For example, to create a privileged task at priority 2 set uxPriority to (2 portPRIVILEGE_BIT ). Priorities are asserted to be less than configMAX_PRIORITIES. If configASSERT is undefined, priorities are silently capped at (configMAX_PRIORITIES - 1). |
| pxCreatedTask | Used to pass a handle to the created task out of the xTaskCreate() function. pxCreatedTask is optional and can be set to NULL. |
| puxStackBuffer | Must point to a StackType_t array that has at least ulStackDepth indexes (see the ulStackDepth parameter above) - the array will be used as the task’s stack, so it must be persistent (not declared on the stack of a function). |
| pxTaskBuffer | Must point to a variable of type StaticTask_t. The variable will be used to hold the new task’s data structures (TCB), so it must be persistent (not declared on the stack of a function). |
If neither puxStackBuffer or pxTaskBuffer are NULL then the task will be created, and the task’s handle is returned. If either puxStackBuffer or pxTaskBuffer is NULL then the task will not be created and NULL will be returned.
/* Dimensions of 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);
/** task code goes here. */
}
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, /* Number of indexes in the xStack array. */
( 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](/Documentation/02-Kernel/04-API-references/02-Task-control/06-vTaskSuspend)( xHandle );
}
// task.h
void vTaskDelete( TaskHandle_t xTask );
INCLUDE_vTaskDelete must be defined as 1 for this function to be available. See the RTOS Configuration documentation for more information.
Remove a task from the RTOS kernels management. The task being deleted will be removed from all ready, blocked, suspended and event lists.
NOTE: If a task deletes another task, the RTOS kernel allocated memory is freed in the API itself. If a task deletes itself, the idle task is responsible for freeing the RTOS kernel allocated memory. 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:
Example:
void vOtherFunction( void )
{
TaskHandle_t xHandle = NULL;
// Create the task, storing the handle.
xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
// Use the handle to delete the task.
if( xHandle != NULL )
{
vTaskDelete( xHandle );
}
}
// led flash
#include "driver/gpio.h"
#include "esp_chip_info.h"
#include "esp_flash.h"
#include "esp_system.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "sdkconfig.h"
#include <inttypes.h>
#include <stdio.h>
#define STACK_SIZE 2048
extern "C" void flash_led_task(void *pvParameters) {
gpio_num_t *gpio_ptr = (gpio_num_t *)pvParameters;
gpio_num_t io_num = *gpio_ptr;
gpio_config_t conf;
conf.mode = GPIO_MODE_OUTPUT;
conf.pin_bit_mask = 1ULL << io_num;
conf.pull_up_en = GPIO_PULLUP_ENABLE;
conf.pull_down_en = GPIO_PULLDOWN_DISABLE;
esp_err_t err = gpio_config(&conf);
printf("errcode %d\r\n", err);
while (true) {
vTaskDelay(pdMS_TO_TICKS(1000));
gpio_set_level(io_num, 1);
printf("led on\r\n");
vTaskDelay(pdMS_TO_TICKS(1000));
gpio_set_level(io_num, 0);
printf("led off\r\n");
}
}
extern "C" void app_main(void) {
BaseType_t xReturned;
TaskHandle_t xHandle;
static gpio_num_t led_gpio = GPIO_NUM_0;
xReturned = xTaskCreate(LED::flash_led_task, "flash_led", STACK_SIZE,
&led_gpio, tskIDLE_PRIORITY, &xHandle);
if (xReturned != pdPASS) {
printf("Task createion failed!\n");
}
}