任务实用程序
[API]

TaskHandle_t xTaskGetCurrentTaskHandle( void );

TaskHandle_t xTaskGetIdleTaskHandle( void );

INCLUDE_xTaskGetIdleTaskHandle 必须设置为 1 才能使用此函数。

返回：

与空闲任务关联的任务句柄。 RTOS 调度器启动时，自动创建空闲任务。

eTaskGetState

eTaskState eTaskGetState( TaskHandle_t xTask );

返回在执行 eTaskGetState() 时任务所在的状态作为枚举类型。

必须在 FreeRTOSConfig.h 中将 INCLUDE_eTaskGetState 设置为 1，eTaskGetState() 才可用。

另请参阅 vTaskGetInfo()。

参数：

xTask

主题任务（正在查询的任务）的句柄。

返回：

下表列出了 eTaskGetState() 为 xTask 参数引用的任务可能存在的每个潜在状态返回的值。

状态	返回值
准备就绪	eReady
运行	eRunning （调用任务正在查询自己的优先级）
已阻塞	eBlocked
已挂起	eSuspended
已删除	eDeleted （任务 TCB 正在等待清理）

pcTaskGetName

char * pcTaskGetName( TaskHandle_t xTaskToQuery );

从任务的句柄中查找任务的名称。

参数：

xTaskToQuery

正在查询的任务的句柄。 xTaskToQuery 可以设置为 NULL，以查询调用任务的名称。

返回：

指向主题任务名称的指针，它是一个标准的以 NULL 结尾的 C 字符串。

xTaskGetHandle

TaskHandle_t xTaskGetHandle( const char *pcNameToQuery );
	

从任务的名称中查找任务的句柄。

注意： 此函数需要较长的时间才能完成，并且只能 为每个任务调用一次。 一旦获得了一个任务的句柄， 它就可以被储存在本地以便重新使用。

必须在 FreeRTOSConfig.h 中将 INCLUDE_xTaskGetHandle 设置为 1，xTaskGetHandle() 才可用。

参数：

pCNAMEToQuery

将返回句柄的任务的文本名称 （作为标准的以 NULL 结尾的 C 字符串）。 请参阅 xTaskCreate() 的 pcName 参数 和 xTaskCreateStatic() API 函数以了解关于设置任务 以字表示（而非字节数）。

返回：

如果可以找到在 pcNameToQuery 中传递名称的任务，则 将返回任务句柄，否则返回 NULL。

xTaskGetTickCount

volatile TickType_t xTaskGetTickCount( void );

无法从 ISR 调用此函数。 使用 xTaskGetTickCountFromISR() 。

返回：

自 vTaskStartScheduler 被调用起的 tick 数。

xTaskGetTickCountFromISR

volatile TickType_t xTaskGetTickCountFromISR( void );

xTaskGetTickCount() 的一个版本，可以从 ISR 中调用。

返回：

自 vTaskStartScheduler 被调用起的 tick 数。

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

configUSE_TRACE_FACILITY 和 configUSE_STATS_FORMATTING_FUNCTIONS 必须 在 FreeRTOSConfig.h 中定位为 1 ，才可使用此函数。 请参阅配置章节了解更多信息。

注意：此函数将在其持续时间内禁用中断。它不是作为 一种正常的应用程序运行时的工具，而是作为调试辅助工具。

该 API 在内部调用 vTaskListTasks 函数，并假设 pcWriteBuffer 的长度为 configSTATS_BUFFER_MAX_LENGTH。 该函数仅适用于向后兼容。建议新应用程序使用 vTaskListTasks 并显式提供 pcWriteBuffer 的长度。

参数：

pcWriteBuffer

一个缓冲区， 上面提到的细节将以 ASCII 形式写入其中。假设此缓冲区 的大小足以容纳产生的报告。 大约为每个任务分配 40 字节的缓冲区就足够了。

vTaskListTasks

void vTaskListTasks( char *pcWriteBuffer, size_t uxBufferLength );

configUSE_TRACE_FACILITY 和 configUSE_STATS_FORMATTING_FUNCTIONS 在 FreeRTOSConfig.h 中必须定义为 1，此函数才可用。 请参阅配置章节了解更多信息。

注意：此函数将在其持续时间内禁用中断。它不是作为正常的应用程序运行时的工具，而是作为调试辅助工具。

vTaskListTasks() 调用 uxTaskGetSystemState()，然后将 uxTaskGetSystemState() 生成的原始数据格式化为人类可读的 (ASCII) 表格，该表格会显示各项任务的状态，包括任务的堆栈高水位线（高水位线数字越小，任务越接近堆栈溢出）。点击此处查看生成的输出示例。

在 ASCII 表中，以下字母用于表示任务的状态：

• 'B' - 已阻塞
• 'R' - 准备就绪
• 'D' - 已删除（等待清理）
• 'S' - 已挂起或已阻塞，没有超时

vTaskListTasks() 是一个仅为方便起见而提供的实用程序函数，并不是内核的一部分。

参数：

pcWriteBuffer	上述详细信息将以 ASCII 形式写入的缓冲区。假设此缓冲区 的大小足以容纳产生的报告。大约为每个任务分配 40 字节的缓冲区就足够了。
uxBufferLength	pcWriteBuffer 的长度。

vTaskStartTrace

void vTaskStartTrace( char * pcBuffer, unsigned long ulBufferSize );

[该函数与旧版跟踪工具有关-在 FreeRTOSV7.1.0 中被删除-用户可能会发现较新的 Trace Hook 宏更容易使用，功能也更强大。］

启动 RTOS 内核活动跟踪。跟踪记录何时运行任务的标识。

跟踪文件以二进制格式存储。使用名为 convtrce.exe 的单独 DOS 实用程序将其转换为一个带制表符的文本文件-可以在电子表格中查看和绘制。

参数：

pcBuffer	跟踪将写入的缓冲区。
ulBufferSize	pcBuffer 的大小（以字节为单位）。跟踪将持续到缓冲区已满或 ulTaskEndTrace () 被调用。

ulTaskEndTrace

unsigned long ulTaskEndTrace( void );

[该函数与旧版跟踪工具有关-在 FreeRTOSV7.1.0 中被删除-用户可能会发现较新的 Trace Hook 宏更容易使用，功能也更强大。］

停止 RTOS 内核活动跟踪。请参阅 vTaskStartTrace()。

返回：

已写入跟踪缓冲区的字节数。

vTaskGetRunTimeStats

void vTaskGetRunTimeStats( char *pcWriteBuffer );
	

configGENERATE_RUN_TIME_STATS、configUSE_STATS_FORMATTING_FUNCTIONS 和 configSUPPORT_DYNAMIC_ALLOCATION 必须全部定义为 1，该函数才可用。该应用程序 还必须提供 portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() 和 portGET_RUN_TIME_COUNTER_VALUE 的定义， 以便分别配置外设定时器/计数器和返回定时器的当前计数值。计数器的频率应该至少是滴答计数的 10 倍。

注意：此函数将在其持续时间内禁用中断。 它不是作为正常的应用程序运行时的工具，而是作为调试辅助工具。

该 API 在内部调用 vTaskGetRunTimeStatistics 函数，并假设 pcWriteBuffer 的长度为 configSTATS_BUFFER_MAX_LENGTH。该函数仅适用于向后兼容。建议新应用程序使用 vTaskGetRunTimeStatistics 并显式提供 pcWriteBuffer 的长度。

参数：

pcWriteBuffer

一个缓冲区， 执行时间将以 ASCII 形式写入其中。 假设此缓冲区足够大， 足以容纳生成的报告。 大约为每个任务分配 40 字节的缓冲区 就足够了。

vTaskGetRunTimeStatistics

void vTaskGetRunTimeStatistics( char *pcWriteBuffer, size_t uxBufferLength );
	

有关此功能的完整说明，请参阅 运行时间统计 页面。

configGENERATE_RUN_TIME_STATS、configUSE_STATS_FORMATTING_FUNCTIONS 和 configSUPPORT_DYNAMIC_ALLOCATION 必须全部定义为 1，该函数才可用。该应用程序 还必须提供 portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() 和 portGET_RUN_TIME_COUNTER_VALUE 的定义， 以便分别配置外设定时器/计数器和返回定时器的当前计数值。计数器的频率应该至少是滴答计数的 10 倍。

注意：此函数将在其持续时间内禁用中断。 它不是作为正常的应用程序运行时的工具，而是作为调试辅助工具。

vTaskGetRunTimeStats() 调用 uxTaskGetSystemState()，然后将 uxTaskGetSystemState() 生成的原始数据格式化为 人类可读的 (ASCII) 表格，显示每个任务在运行状态下花费的时间（每个任务消耗了多少 CPU 时间）。 数据以 绝对值和百分比值的形式提供。 绝对值的分辨率取决于应用程序提供的运行时间统计时钟的频率。

vTaskGetRunTimeStatistics() 是一个仅为方便起见而提供的实用程序函数。 并不是内核的一部分。 请参阅 vTaskListTasks() 了解生成每个任务状态信息的实用函数。

参数：

pcWriteBuffer	一个缓冲区， 执行时间将以 ASCII 形式写入其中。 假设此缓冲区足够大， 足以容纳生成的报告。 大约为每个任务分配 40 字节的缓冲区 就足够了。
uxBufferLength	pcWriteBuffer 的长度。

vTaskGetIdleRunTimeCounter

TickType_t xTaskGetIdleRunTimeCounter( void );
	

configGENERATE_RUN_TIME_STATS 和 INCLUDE_xTaskGetIdleTaskHandle 必须都定义为 1，该函数才可用。 然后， 该应用程序还必须提供 portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() 和 portGET_RUN_TIME_COUNTER_VALUE 的定义， 以分别配置外设的定时器/计数器和返回定时器的当前计数值。 建议确保定时器的频率至少是滴答计数的 10 倍。

返回：

空闲任务的运行时间计数器。 可利用该函数来确定空闲任务获得了多少 CPU 时间。 有关运行时间统计功能的完整说明， 请参阅 运行时间统计 页面。

ulTaskGetRunTimeCounter

configRUN_TIME_COUNTER_TYPE ulTaskGetRunTimeCounter( const TaskHandle_t xTask );
	

configUSE_APPLICATION_TASK_TAG 必须定义为 1，这些函数才可用。该应用程序还必须提供 portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() 和 portGET_RUN_TIME_COUNTER_VALUE () 的定义，以分别配置外设的定时器/计数器和返回定时器的当前计数值。计数器的频率应该至少是滴答计数的 10 倍 。

将 configGENERATE_RUN_TIME_STATS 设置为 1 将导致为每个任务存储总累计执行时间。ulTaskGetRunTimeCounter() 返回给定任务的总执行时间。

返回：

给定任务的总运行时间。这是任务实际执行的时间。时间单位取决于使用 portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() 和 portGET_RUN_TIME_COUNTER_VALUE() 宏配置的频率。

ulTaskGetRunTimePercent

configRUN_TIME_COUNTER_TYPE ulTaskGetRunTimePercent( const TaskHandle_t xTask );
	

configUSE_APPLICATION_TASK_TAG 必须定义为 1，这些函数才可用。该应用程序还必须提供 portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() 和 portGET_RUN_TIME_COUNTER_VALUE () 的定义，以分别配置外设的定时器/计数器和返回定时器的当前计数值。计数器的频率应该至少是滴答计数的 10 倍 。

将 configGENERATE_RUN_TIME_STATS 设置为 1 将导致为每个任务存储总累计执行时间。ulTaskGetRunTimePercent() 返回给定任务所用 CPU 时间的百分比。

返回：

给定任务所用 CPU 时间的百分比。

ulTaskGetIdleRunTimeCounter

configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimeCounter( void );
	

configUSE_APPLICATION_TASK_TAG 必须定义为 1，这些函数才可用。该应用程序还必须提供 portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() 和 portGET_RUN_TIME_COUNTER_VALUE () 的定义，以分别配置外设的定时器/计数器和返回定时器的当前计数值。计数器的频率应该至少是滴答计数的 10 倍 。

将 configGENERATE_RUN_TIME_STATS 设置为 1 将导致为每个任务存储总累计执行时间。ulTaskGetRunTimeCounter() 返回空闲任务的总执行时间。

请注意，只有在没有其他任务以空闲优先级执行、不使用无滴答空闲并且将 configIDLE_SHOULD_YIELD 设置为 0 的情况下， 空闲时间才能很好地反映系统中的闲置时间。

返回：

空闲任务的总运行时间。这是空闲任务实际执行的时间。时间单位取决于 使用 portCONFIGURE_TIMER_FOR_RUN_TIME_STATS () 和 portGET_RUN_TIME_COUNTER_VALUE () 宏配置的频率。

ulTaskGetIdleRunTimePercent

configRUN_TIME_COUNTER_TYPE ulTaskGetIdleRunTimePercent( void );
	

configUSE_APPLICATION_TASK_TAG 必须定义为 1，这些函数才可用。该应用程序还必须提供 portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() 和 portGET_RUN_TIME_COUNTER_VALUE () 的定义，以分别配置外设的定时器/计数器和返回定时器的当前计数值。计数器的频率应该至少是滴答计数的 10 倍 。

将 configGENERATE_RUN_TIME_STATS 设置为 1 将导致为每个任务存储总累计执行时间。ulTaskGetIdleRunTimePercent() 返回空闲任务所用 CPU 时间的百分比。

请注意，只有在没有其他任务以空闲优先级执行、不使用无滴答空闲并且将 configIDLE_SHOULD_YIELD 设置为 0 的情况下， 空闲时间才能很好地反映系统中的闲置时间。

返回：

空闲任务所用 CPU 时间的百分比。