FreeRTOS api库函数之Task Utilities（任务实用程序）

uxTaskGetSystemState（）
UBaseType_t uxTaskGetSystemState（TaskStatus_t * const pxTaskStatusArray，const UBaseType_t uxArraySize，          unsigned long * const pulTotalRunTime）;
uxTaskGetSystemState（）为系统中的每个任务填充TaskStatus_t结构。 TaskStatus_t结构包含任务句柄，任务名称，任务优先级，任务状态以及任务消耗的总运行时间等成员。
注意：此功能仅用于调试使用，因为它的使用导致调度程序在较长时间内保持挂起状态。
必须在FreeRTOSConfig.h中将configUSE_TRACE_FACILITY定义为1才能使uxTaskGetSystemState（）可用。
参数：
    pxTaskStatusArray 指向TaskStatus_t结构数组的指针。对于受RTOS控制的每个任务，该数组必须至少包含一个TaskStatus_t结构。可以使用uxTaskGetNumberOfTasks（）API函数确定RTOS控制下的任务数。
    uxArraySize pxTaskStatusArray 参数指向的数组的大小。大小指定为数组中的索引数（数组中包含的TaskStatus_t结构的数量），而不是数组中的字节数。
    pulTotalRunTime 如果在FreeRTOSConfig.h中将configGENERATE_RUN_TIME_STATS设置为1，那么* pulTotalRunTime由uxTaskGetSystemState（）设置为自目标引导以来的总运行时间（由运行时统计时钟定义）。 pulTotalRunTime可以设置为NULL以省略总运行时间值。
返回：
    由uxTaskGetSystemState（）填充的TaskStatus_t结构的数量。这应该等于uxTaskGetNumberOfTasks（）API函数返回的数字，但如果uxArraySize参数中传递的值太小，则该值将为零。

vTaskGetInfo（）
void vTaskGetInfo（TaskHandle_t xTask，TaskStatus_t * pxTaskStatus， BaseType_t xGetFreeStackSpace，
                   eTaskState eState）;
uxTaskGetSystemState（）为系统中的每个任务填充TaskStatus_t结构，而vTaskGetInfo（）仅为单个任务填充TaskStatus_t结构。 TaskStatus_t结构包含任务句柄，任务名称，任务优先级，任务状态以及任务消耗的总运行时间等成员。
注意：此功能仅用于调试使用，因为它的使用导致调度程序在较长时间内保持挂起状态。
必须在FreeRTOSConfig.h中将configUSE_TRACE_FACILITY定义为1才能使vTaskGetInfo（）可用。
参数：
    xTask 正在查询的任务的句柄。将xTask设置为NULL将返回有关调用任务的信息。
    pxTaskStatus  pxTaskStatus指向的TaskStatus_t结构将填充有关xTask参数中传递的句柄引用的任务的信息。
    xGetFreeStackSpace  TaskStatus_t结构包含一个成员，用于报告正在查询的任务的堆栈高水位线。堆栈高水位线是已经存在的最小堆栈空间量，因此数字越接近零，任务越接近其堆栈溢出。计算堆栈高水位标记需要相对较长的时间，并且可以使系统暂时无响应 - 因此提供xGetFreeStackSpace参数以允许跳过高水位标记检查。如果xGetFreeStackSpace未设置为pdFALSE，则高水印值将仅写入TaskStatus_t结构。
    eState  TaskStatus_t结构包含一个成员，用于报告正在查询的任务的状态。获取任务状态并不像简单赋值那么快 - 因此提供eState参数以允许从TaskStatus_t结构中省略状态信息。要获取状态信息，请将eState设置为eInvalid - 否则eState中传递的值将被报告为TaskStatus_t结构中的任务状态。

xTaskGetApplicationTaskTag
TaskHookFunction_t xTaskGetApplicationTaskTag（TaskHandle_t xTask）;
返回与任务关联的“标签”值。 标记值的含义和用法由应用程序编写者定义。 RTOS内核本身通常不会访问标记值。
此功能仅适用于高级用户。
必须将configUSE_APPLICATION_TASK_TAG定义为1才能使此功能可用。
参数：
     xTask 正在查询的任务的句柄。 任务可以使用NULL作为参数值来查询自己的标记值。
返回：
     正在查询的任务的“标签”值。

xTaskGetCurrentTaskHandle
TaskHandle_t xTaskGetCurrentTaskHandle（void）;
必须将INCLUDE_xTaskGetCurrentTaskHandle设置为1才能使此功能可用。
返回：
     当前正在运行（调用）任务的句柄。

xTaskGetIdleTaskHandle
TaskHandle_t xTaskGetIdleTaskHandle（void）;
必须将INCLUDE_xTaskGetIdleTaskHandle设置为1才能使此功能可用。
返回：
     与空闲任务关联的任务句柄。 启动RTOS调度程序时会自动创建空闲任务。

eTaskGetState
eTaskState eTaskGetState（TaskHandle_t xTask）;
以枚举类型返回执行eTaskGetState（）时任务存在的状态。
在FreeRTOSConfig.h中，INCLUDE_eTaskGetState必须设置为1才能使eTaskGetState（）可用。
参数：
     xTask主题任务的句柄（正在查询的任务）。
返回：
     返回任务存在的状态。

xTaskGetHandle
TaskHandle_t xTaskGetHandle（const char * pcNameToQuery）;
从任务名称中查找任务的句柄。
注意：此功能需要相对较长的时间才能完成，并且每个任务只应调用一次。 一旦获得任务的句柄，就可以将其存储在本地以便重复使用。
在FreeRTOSConfig.h中必须将INCLUDE_xTaskGetHandle设置为1才能使xTaskGetHandle（）可用。
参数：
     pcNameToQuery 将为其返回句柄的任务的文本名称（作为标准C NULL终止字符串）。
返回：
     如果可以找到在pcNameToQuery中传递了名称的任务，则返回任务的句柄，否则返回NULL。

xTaskGetTickCount
volatile TickType_t xTaskGetTickCount（void）;
无法从ISR调用此功能。 请改用xTaskGetTickCountFromISR（）。
返回：
     自调用vTaskStartScheduler以来的滴答计数。

xTaskGetTickCountFromISR
volatile TickType_t xTaskGetTickCountFromISR（void）;
可以从ISR调用的xTaskGetTickCount（）版本。
返回：
     自调用vTaskStartScheduler以来的滴答计数。

xTaskGetSchedulerState
BaseType_t xTaskGetSchedulerState（void）;
返回：
     以下常量之一（在task.h中定义）： taskSCHEDULER_NOT_STARTED，taskSCHEDULER_RUNNING，taskSCHEDULER_SUSPENDED。
     必须在FreeRTOSConfig.h中将INCLUDE_xTaskGetSchedulerState或configUSE_TIMERS设置为1才能使此功能可用。

uxTaskGetNumberOfTasks
UBaseType_t uxTaskGetNumberOfTasks（void）;
返回：
     RTOS内核当前正在管理的任务数。 这包括所有就绪，阻止和暂停的任务。 已被删除但尚未被空闲任务释放的任务也将包含在计数中。

vTaskList
void vTaskList（char * pcWriteBuffer）;
必须在FreeRTOSConfig.h中将configUSE_TRACE_FACILITY和configUSE_STATS_FORMATTING_FUNCTIONS定义为1才能使此功能可用。
注意：此功能将在其持续时间内禁用中断。它不适用于正常的应用程序运行时使用，而是作为调试辅助工具。
vTaskList（）调用uxTaskGetSystemState（），然后将uxTaskGetSystemState（）生成的原始数据格式化为人类可读（ASCII）表，显示每个任务的状态，包括任务的堆栈高水位标记（高水位标记号越小）越接近任务已经溢出其堆栈）。
在ASCII表中，以下字母用于表示任务的状态：
    'B' - 被阻止
    'R' - 准备好了
    'D' - 删除（等待清理）
    'S' - 暂停，或在没有超时的情况下被阻止
vTaskList（）是为方便起见而提供的实用程序功能。它不被视为内核的一部分。请参阅vTaskGetRunTimeStats（）以获取生成类似的运行时任务利用率信息表的实用程序函数。
参数：
    pcWriteBuffer 一个缓冲区，其中将以ASCII格式写入上述详细信息。假设此缓冲区足够大以包含生成的报告。每个任务大约40个字节就足够了。

vTaskStartTrace
void vTaskStartTrace（char * pcBuffer，unsigned long ulBufferSize）;

【该功能与遗留跟踪实用程序相关 - 已在FreeRTOS V7.1.0中删除 - 用户可能会发现更新的跟踪钩宏更容易使用。】
启动RTOS内核活动跟踪。 跟踪记录何时运行的任务的标识。
跟踪文件以二进制格式存储。 一个名为convtrce.exe的独立DOS实用程序用于将其转换为制表符分隔的文本文件，可以在电子表格中查看和绘制。
参数：
     pcBuffer 将写入跟踪的缓冲区。
     ulBufferSize  pcBuffer的大小（以字节为单位）。 跟踪将继续，直到缓冲区完全或调用ulTaskEndTrace（）。

ulTaskEndTrace
unsigned long ulTaskEndTrace（void）;
[该功能与遗留跟踪实用程序相关 - 已在FreeRTOS V7.1.0中删除 - 用户可能会发现更新的跟踪钩宏更容易使用。]
停止RTOS内核活动跟踪。
返回：
     已写入跟踪缓冲区的字节数。

vTaskGetRunTimeStats
void vTaskGetRunTimeStats（char * pcWriteBuffer）;
必须将configGENERATE_RUN_TIME_STATS和configUSE_STATS_FORMATTING_FUNCTIONS定义为1才能使此功能可用。然后，应用程序还必须提供portCONFIGURE_TIMER_FOR_RUN_TIME_STATS（）和portGET_RUN_TIME_COUNTER_VALUE的定义，以配置外设定时器/计数器并分别返回定时器当前计数值。计数器应至少是滴答计数频率的10倍。
注意：此功能将在其持续时间内禁用中断。它不适用于正常的应用程序运行时使用，而是作为调试辅助工具。
vTaskGetRunTimeStats（）调用uxTaskGetSystemState（），然后将uxTaskGetSystemState（）生成的原始数据格式化为人类可读（ASCII）表，该表显示每个任务在运行状态下花费的时间（每个任务消耗了多少CPU时间） 。数据以绝对值和百分比值提供。绝对值的分辨率取决于应用程序提供的运行时统计时钟的频率。
vTaskGetRunTimeStats（）是一个仅为方便起见而提供的实用程序函数。它不被视为内核的一部分。请参阅vTaskList（）以获取生成有关每个任务状态信息的实用程序函数。
参数：
    pcWriteBuffer 以ASCII格式写入执行时间的缓冲区。假设此缓冲区足够大以包含生成的报告。每个任务大约40个字节就足够了。

vTaskSetApplicationTaskTag
void vTaskSetApplicationTaskTag（TaskHandle_t xTask， TaskHookFunction_t pxTagValue）;
必须将configUSE_APPLICATION_TASK_TAG定义为1才能使此功能可用。
可以为每个任务分配“标签”值。 此值仅供应用程序使用 -  RTOS内核本身不以任何方式使用它。 RTOS跟踪宏文档页面提供了应用程序如何使用此功能的一个很好的示例。
参数：
     xTask 正在为其分配标记值的任务的句柄。 将xTask传递为NULL会导致将标记分配给调用任务。
     pxTagValue 分配给任务标记的值。 这是TaskHookFunction_t类型，允许将函数指针指定为标记，但实际上可以分配任何值。

xTaskCallApplicationTaskHook
BaseType_t xTaskCallApplicationTaskHook（ TaskHandle_t xTask， void * pvParameter）;
必须将configUSE_APPLICATION_TASK_TAG定义为1才能使此功能可用。
可以为每个任务分配“标签”值。通常，此值仅供应用程序使用，RTOS内核不访问它。但是，可以使用标记为任务分配钩子（或回调）函数 - 通过调用xTaskCallApplicationTaskHook（）执行钩子函数。每个任务都可以定义自己的回调，或者根本不定义回调。
尽管可以使用第一个函数参数来调用任何任务的钩子函数，但是任务钩子函数的最常见用途是使用跟踪钩子宏，如下面给出的示例所示。
任务钩子函数必须具有类型TaskHookFunction_t，即采用void *参数，并返回BaseType_t类型的值。 void *参数可用于将任何信息传递到钩子函数。
参数：
    xTask 正在调用其钩子函数的任务的句柄。将NULL作为xTask传递将调用与当前正在执行的任务关联的钩子函数。
    pvParameter 传递给钩子函数的值。这可以是指向结构的指针，也可以是数字值。

vTaskSetThreadLocalStoragePointer
void vTaskSetThreadLocalStoragePointer（TaskHandle_t xTaskToSet， BaseType_t xIndex， void * pvValue）
在任务的线程本地存储阵列中设置值。
此功能仅适用于高级用户。
参数：
     xTaskToSet 正在向其写入线程本地数据的任务的句柄。 任务可以使用NULL作为参数值写入其自己的线程本地数据。
     xIndex 正在写入数据的线程本地存储阵列的索引。
     可用数组索引的数量由FreeRTOSConfig.h中的configNUM_THREAD_LOCAL_STORAGE_POINTERS编译时配置常量设置。
     pvValue 写入xIndex参数指定的索引的值。

pvTaskGetThreadLocalStoragePointer
void * pvTaskGetThreadLocalStoragePointer（TaskHandle_t xTaskToQuery，  BaseType_t xIndex）;
从任务的线程本地存储阵列中检索值。
此功能仅适用于高级用户。
参数：
     xTaskToQuery 正在从中读取线程本地数据的任务的句柄。 任务可以使用NULL作为参数值来读取自己的线程本地数据。
     xIndex 正在读取数据的线程本地存储阵列的索引。
     可用数组索引的数量由FreeRTOSConfig.h中的configNUM_THREAD_LOCAL_STORAGE_POINTERS编译时配置常量设置。
返回：
     存储在任务xTaskToQuery的线程本地存储阵列的索引位置xIndex中的值。

vTaskSetTimeOutState（）
void vTaskSetTimeOutState（TimeOut_t * const pxTimeOut）;
此功能仅适用于高级用户。
任务可以进入阻止状态以等待事件。通常，任务不会无限期地等待阻塞状态，而是指定超时时间。如果超时期限在任务等待事件发生之前到期，则任务将从阻止状态中删除。
如果任务在等待事件发生时不止一次进入和退出阻塞状态，则必须调整每次任务进入阻塞状态时使用的超时，以确保在阻塞状态下花费的所有时间总和不超过最初指定的超时期限。 xTaskCheckForTimeOut（）执行调整，考虑到偶然发生的事件，例如滴答计数溢出，否则会导致手动调整容易出错。
vTaskSetTimeOutState（）与xTaskCheckForTimeOut（）一起使用。调用vTaskSetTimeOutState（）来设置初始条件，之后可以调用xTaskCheckForTimeOut（）来检查超时条件，如果没有发生超时，则调整剩余的块时间。
参数：
    pxTimeOut 指向结构的指针，该结构将被初始化以保存确定是否发生超时所必需的信息。

xTaskCheckForTimeOut（）
BaseType_t xTaskCheckForTimeOut（TimeOut_t * const pxTimeOut，TickType_t * const pxTicksToWait）;
此功能仅适用于高级用户。
任务可以进入阻止状态以等待事件。通常，任务不会无限期地等待阻塞状态，而是指定超时时间。如果超时期限在任务等待事件发生之前到期，则任务将从阻止状态中删除。
如果任务在等待事件发生时不止一次进入和退出阻塞状态，则必须调整每次任务进入阻塞状态时使用的超时，以确保在阻塞状态下花费的所有时间总和不超过最初指定的超时期限。 xTaskCheckForTimeOut（）执行调整，考虑到偶然发生的事件，例如滴答计数溢出，否则会导致手动调整容易出错。
xTaskCheckForTimeOut（）与vTaskSetTimeOutState（）一起使用。调用vTaskSetTimeOutState（）来设置初始条件，之后可以调用xTaskCheckForTimeOut（）来检查超时条件，如果没有发生超时，则调整剩余的块时间。
参数：
    pxTimeOut 指向结构的指针，该结构包含确定是否发生超时所必需的信息。使用vTaskSetTimeOutState（）初始化pxTimeOut。
    pxTicksToWait 用于传递调整后的块时间，这是在考虑已经在阻塞状态下花费的时间之后剩余的块时间。
返回：
    如果返回pdTRUE，则不会保留块时间，并且发生超时。
    如果返回pdFALSE，则会保留一些块时间，因此未发生超时。