FreeRTOS API参考——任务创建

Modules

• xTaskCreate

• xTaskCreateStatic

TaskHandle_t
task. h

    引用任务的类型。 例如，对xTaskCreate的调用（通过指针参数）返回TaskHandle_t变量，然后可以将该变量用作vTaskDelete的参数以删除任务。

 

xTaskCreate

task. h

BaseType_t xTaskCreate( TaskFunction_t pvTaskCode, 
                                            const char * const pcName, 
                                            configSTACK_DEPTH_TYPE usStackDepth, 
                                            void *pvParameters, 
                                            UBaseType_t uxPriority, 
                                            TaskHandle_t *pxCreatedTask );

 

        创建一个新任务，并将其添加到准备运行的任务列表中。 要使此RTOS API函数可用，必须在FreeRTOSConfig.h中将configSUPPORT_DYNAMIC_ALLOCATION设置为1，或将其保留为未定义状态（在这种情况下，它将默认为1）。

        每个任务都需要用于保持任务状态的RAM，并由任务用作其堆栈。 如果使用xTaskCreate（）创建任务，则从FreeRTOS堆中自动分配所需的RAM。 如果使用xTaskCreateStatic（）创建任务，则RAM由应用程序编写器提供，因此可以在编译时静态分配。 有关更多信息，请参见静态与动态分配页面。

        如果您使用的是FreeRTOS-MPU，则建议使用xTaskCreateRestricted（）代替xTaskCreate（）。

 

参数：

pvTaskCode	指向任务输入功能的指针（仅是实现任务的功能的名称，请参见下面的示例）。     任务通常被实现为无限循环，并且决不能尝试从其实现函数中返回或退出。但是，任务可以自行删除。
pcName	任务的描述性名称。 这主要用于方便调试，但也可以用于获取任务句柄。 使用FreeRTOSConfig.h中的configMAX_TASK_NAME_LEN参数设置任务名称的最大长度。
usStackDepth	分配用作任务堆栈的字数（不是字节！）。 例如，如果堆栈为16位宽，而usStackDepth为100，则将分配200个字节用作任务的堆栈。 再举一个例子，如果堆栈为32位宽，而usStackDepth为400，则将分配1600字节用作任务的堆栈。 堆栈深度乘以堆栈宽度不得超过size_t类型变量中可以包含的最大值。
pvParameters	该值将作为任务的参数传递到创建的任务中。 如果将pvParameters设置为变量的地址，则在创建的任务执行时该变量必须仍然存在–因此传递堆栈变量的地址无效。
uxPriority	创建的任务将执行的优先级。 包含MPU支持的系统可以通过在uxPrriority中设置portPRIVILEGE_BIT位来选择在特权（系统）模式下创建任务。 例如，要创建优先级为2的特权任务，请将uxPriority设置为（2 | portPRIVILEGE_BIT）。
pxCreatedTask	用于通过xTaskCreate（）函数将句柄传递给创建的任务。 pxCreatedTask是可选的，可以设置为NULL。

返回值：

如果任务创建成功，则返回pdPASS。 否则，返回errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY。

 

用法示例：

/* Task to be 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 xTaskCreate() below.
    configASSERT( ( ( uint32_t ) pvParameters ) == 1 );

    for( ;; )
    {
        /* Task code goes here. */
    }
}

/* Function that creates a task. */
void vOtherFunction( void )
{
BaseType_t xReturned;
TaskHandle_t xHandle = NULL;

    /* Create the task, storing the handle. */
    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 );
    }
}

xTaskCreateStatic

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 );

 

创建一个新任务，并将其添加到准备运行的任务列表中。 必须在FreeRTOSConfig.h中将configSUPPORT_STATIC_ALLOCATION设置为1，此RTOS API函数才可用。

 

每个任务都需要用于保持任务状态的RAM，并由任务用作其堆栈。 如果使用xTaskCreate（）创建任务，则从FreeRTOS堆中自动分配所需的RAM。 如果使用xTaskCreateStatic（）创建任务，则应用程序编写器将提供RAM，这将导致大量参数，但允许在编译时静态分配RAM。 有关更多信息，请参见静态与动态分配页面。

 

如果您使用的是FreeRTOS-MPU，则建议使用xTaskCreateRestricted（）代替xTaskCreateStatic（）。

 

参数：

pvTaskCode	指向任务输入功能的指针（仅是实现任务的功能的名称，请参见下面的示例）。     任务通常被实现为无限循环，并且决不能尝试从其实现函数中返回或退出。但是，任务可以自行删除。
pcName	任务的描述性名称。 这主要用于方便调试，但也可以用于获取任务句柄。 使用FreeRTOSConfig.h中的configMAX_TASK_NAME_LEN参数设置任务名称的最大长度。
usStackDepth	分配用作任务堆栈的字数（不是字节！）。 例如，如果堆栈为16位宽，而usStackDepth为100，则将分配200个字节用作任务的堆栈。 再举一个例子，如果堆栈为32位宽，而usStackDepth为400，则将分配1600字节用作任务的堆栈。 堆栈深度乘以堆栈宽度不得超过size_t类型变量中可以包含的最大值。
pvParameters	该值将作为任务的参数传递到创建的任务中。 如果将pvParameters设置为变量的地址，则在创建的任务执行时该变量必须仍然存在–因此传递堆栈变量的地址无效。
uxPriority	创建的任务将执行的优先级。 包含MPU支持的系统可以通过在uxPrriority中设置portPRIVILEGE_BIT位来选择在特权（系统）模式下创建任务。 例如，要创建优先级为2的特权任务，请将uxPriority设置为（2 | portPRIVILEGE_BIT）。
puxStackBuffer	必须指向至少具有ulStackDepth索引的StackType_t数组（请参见上面的ulStackDepth参数）–该数组将用作任务的堆栈，因此必须是持久性的（未在函数的堆栈上声明）。
pxTaskBuffer	必须指向StaticTask_t类型的变量。 该变量将用于保存新任务的数据结构（TCB），因此它必须是持久性的（未在函数堆栈中声明）。

返回值：

如果puxStackBuffer或pxTaskBuffer都不为NULL，则将创建任务，并返回任务的句柄。 如果puxStackBuffer或pxTaskBuffer为NULL，则不会创建任务，并且将返回NULL。

 

用法示例：

/* 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,      /* 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( xHandle );
}