FreeRTOS api库函数之Task Creation 和 Task Control（任务创建和任务控制）

 

TaskHandle_t

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

xTaskCreate：
 BaseType_t xTaskCreate（TaskFunction_t pvTaskCode， const char * const pcName，unsigned short usStackDepth，            void * pvParameters，   UBaseType_t uxPriority，  TaskHandle_t * pxCreatedTask ）;
创建一个新任务并将其添加到准备运行的任务列表中。在FreeRTOSConfig.h中，configSUPPORT_DYNAMIC_ALLOCATION必须设置为1，或者保留未定义（在这种情况下默认为1），以使此RTOS API函数可用。
每个任务都需要用于保存任务状态的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。否则返回错误的COULD_NOT_ALLOCATE_REQUIRED_MEMORY。

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

创建一个新任务并将其添加到准备运行的任务列表中。 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参数设置任务名称的最大长度。
    ulStackDepth puxStackBuffer 参数用于将StackType_t变量数组传递给xTaskCreateStatic（）。 ulStackDepth必须设置为数组中的索引数。

    pvParameters 将作为任务参数传递到创建任务的值。

    如果将pvParameters设置为变量的地址，则在创建的任务执行时该变量必须仍然存在 - 因此传递堆栈变量的地址无效。
    uxPriority 创建的任务将执行的优先级。

    包含MPU支持的系统可以选择通过在uxPrriority中设置位portPRIVILEGE_BIT以特权（系统）模式创建任务。例如，要以优先级2创建特权任务，请将uxPriority设置为（2 | portPRIVILEGE_BIT）。
    puxStackBuffe 必须指向至少具有ulStackDepth索引的StackType_t数组（请参阅上面的ulStackDepth参数） - 该数组将用作任务的堆栈，因此必须是持久的（未在函数堆栈中声明）。
    pxTaskBuffer 必须指向StaticTask_t类型的变量。该变量将用于保存新任务的数据结构（TCB），因此它必须是持久的（不在函数的堆栈上声明）。

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

vTaskDelete
void vTaskDelete（TaskHandle_t xTask）;
必须将INCLUDE_vTaskDelete定义为1才能使此功能可用。
从RTOS内核管理中删除任务。 正在删除的任务将从所有就绪，阻止，暂停和事件列表中删除。
注意：idle任务负责从已删除的任务中释放RTOS内核分配的内存。 因此，如果应用程序对vTaskDelete（）进行任何调用，则空闲任务不会缺少微控制器处理时间。 任务代码分配的内存不会自动释放，应在删除任务之前释放。
参数：
     xTask 要删除的任务的句柄。 传递NULL将导致当前调用任务被删除。

vTaskDelay
void vTaskDelay（const TickType_t xTicksToDelay）;
必须将INCLUDE_vTaskDelay定义为1才能使此功能可用。 。
延迟给定数量的滴答的任务。任务保持阻塞的实际时间取决于滴答速率。常量portTICK_PERIOD_MS可用于根据滴答速率计算实时 - 具有一个滴答周期的分辨率。
vTaskDelay（）指定任务希望相对于调用vTaskDelay（）的时间取消阻止的时间。例如，指定100个刻度的块周期将导致任务在调用vTaskDelay（）后取消阻止100个刻度。因此，vTaskDelay（）不提供控制周期性任务频率的好方法，因为通过代码的路径以及其他任务和中断活动将影响调用vTaskDelay（）的频率，从而影响时间下一个任务执行的位置。请参阅vTaskDelayUntil（）以获取旨在促进固定频率执行的替代API函数。它通过指定调用任务应解除阻塞的绝对时间（而不是相对时间）来完成此操作。
参数：
    xTicksToDelay 调用任务应阻止的时间段（以滴答周期为单位）。

vTaskDelayUntil
void vTaskDelayUntil（TickType_t * pxPreviousWakeTime， const TickType_t xTimeIncrement）;
将任务延迟到指定时间。周期性任务可以使用此功能来确保恒定的执行频率。INCLUDE_vTaskDelayUntil必须定义为1才能使此功能可用。
此函数在一个重要方面与vTaskDelay（）不同：vTaskDelay（）指定任务希望相对于调用vTaskDelay（）的时间取消阻止的时间，而vTaskDelayUntil（）指定任务希望的绝对时间打开。
vTaskDelay（）将导致任务在调用vTaskDelay（）时阻塞指定的滴答数。因此，很难使用vTaskDelay（）来生成固定的执行频率，因为调用vTaskDelay（）之后的任务解除阻塞和下一次调用vTaskDelay（）的任务之间的时间可能不会被修复[任务可能会有所不同通过调用之间的代码路径，或者每次执行时可能会被中断或抢占不同的次数]。
而vTaskDelay（）指定相对于调用函数的时间的唤醒时间，而vTaskDelayUntil（）指定它希望解除阻塞的绝对（准确）时间。
应该注意的是，如果vTaskDelayUntil（）用于指定已经过去的唤醒时间，则它将立即返回（不阻塞）。因此，使用vTaskDelayUntil（）定期执行的任务将不得不重新计算其所需的唤醒时间，如果由于任何原因暂停执行定期执行（例如，任务暂时置于Suspended状态）导致任务错过一个或更多的定期执行。这可以通过检查通过引用传递的变量作为针对当前滴答计数的pxPreviousWakeTime参数来检测。然而，在大多数使用场景下，这不是必需的。
常量portTICK_PERIOD_MS可用于根据滴答速率计算实时 - 具有一个滴答周期的分辨率。
通过调用vTaskSuspendAll（）暂停RTOS调度程序时，不得调用此函数。
参数：
    pxPreviousWakeTime 指向一个变量的指针，该变量保存上次解除阻塞任务的时间。必须在首次使用之前使用当前时间初始化变量（请参见下面的示例）。在此之后，变量在vTaskDelayUntil（）中自动更新。
    xTimeIncrement 循环时间段。该任务将在时间解锁（* pxPreviousWakeTime + xTimeIncrement）。使用相同的    xTimeIncrement参数值调用vTaskDelayUntil将导致任务以固定的间隔周期执行。

uxTaskPriorityGet
UBaseType_t uxTaskPriorityGet（TaskHandle_t xTask）;
获取任何任务的优先级。
INCLUDE_uxTaskPriorityGet必须定义为1才能使此功能可用。
参数：
     xTask要查询的任务的句柄。 传递NULL句柄会导致返回调用任务的优先级。
返回值：
     xTask的优先级。

vTaskPrioritySet
void vTaskPrioritySet（TaskHandle_t xTask，UBaseType_t uxNewPriority）;
设置任何任务的优先级。
必须将INCLUDE_vTaskPrioritySet定义为1才能使此功能可用。
如果设置的优先级高于当前正在执行的任务，则在函数返回之前将发生上下文切换。
参数：
     xTask 处理正在设置优先级的任务。 传递NULL句柄会导致设置调用任务的优先级。
     uxNewPriority  将设置任务的优先级。

vTaskSuspend
void vTaskSuspend（TaskHandle_t xTaskToSuspend）;
暂停任何任务。 暂停任务时，永远不会获得任何微控制器处理时间，无论其优先级如何。
必须将INCLUDE_vTaskSuspend定义为1才能使此功能可用。
对vTaskSuspend的调用不是累积的 - 即在同一任务上调用vTaskSuspend（）两次仍然只需要调用vTaskResume（）来准备挂起的任务。
参数：
     xTaskToSuspend 处理被挂起的任务。 传递NULL句柄将导致调用任务被挂起。

vTaskResume
void vTaskResume（TaskHandle_t xTaskToResume）;
恢复暂停的任务。
必须将INCLUDE_vTaskSuspend定义为1才能使此功能可用。 有关更多信息，请参阅RTOS配置文档。
通过对vTaskSuspend（）的一次或多次调用暂停的任务将通过单次调用vTaskResume（）再次运行。
参数：
     xTaskToResume处理正在准备的任务。

xTaskResumeFromISR
BaseType_t xTaskResumeFromISR（TaskHandle_t xTaskToResume）;
用于恢复可以在ISR中调用的挂起任务的函数。
INCLUDE_vTaskSuspend和INCLUDE_xTaskResumeFromISR必须定义为1才能使此功能可用。
通过对xTaskResumeFromISR（）的单次调用，可以再次运行已被一个或多个对vTaskSuspend（）的调用暂停的任务。
xTaskResumeFromISR（）通常被认为是一个危险的函数，因为它的动作没有被锁存。因此，如果中断有可能在任务被挂起之前到达，那么它绝对不应该用于将任务与中断同步，因此中断会丢失。使用信号量，或者更好的直接到任务通知，将避免这种可能性。提供了使用直接到任务通知的工作示例。
参数：
    xTaskToResume 处理正在准备的任务。
返回值：
    pdTRUE。如果恢复任务应导致上下文切换，否则为pdFALSE。 ISR使用它来确定ISR之后是否需要上下文切换。

xTaskAbortDelay
BaseType_t xTaskAbortDelay（TaskHandle_t xTask）;
强制任务退出阻止状态，并进入就绪状态，即使任务处于阻塞状态等待的事件尚未发生，并且任何指定的超时未到期。
必须将INCLUDE_xTaskAbortDelay定义为1才能使此功能可用。
参数：
     xTask 将被强制退出阻止状态的任务句柄。
     要获取任务的句柄，请使用xTaskCreate（）创建任务并使用pxCreatedTask参数，或使用xTaskCreateStatic（）创建任务并存储返回的值，或者在调用xTaskGetHandle（）时使用任务的名称。
返回：
     如果xTask引用的任务未处于阻塞状态，则返回pdFAIL。 否则返回pdPASS。