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