任务相关API函数

任务相关API函数介绍

在 FreeRTOS 官方在线文档的网页页面中，通过查看 API 参考，可以看到官方列出的FreeRTOS 任务相关的 API 函数，如下图所示：

以上部分 FreeRTOS 任务相关的 API 函数描述，如下表所示：

函数	描述
uxTaskPriorityGet（）	获取任务优先级
vTaskPrioritySet（）	设置任务优先级
uxTaskGetSystemState（）	获取所有任务的状态信息
vTaskGetInfo（）	获取单个任务的状态信息
xTaskGetApplicationTaskTag（）	获取任务 Tag
xTaskGetCurrentTaskHandle（）	获取当前任务的任务句柄
xTaskGetHandle（）	获取指定任务的任务句柄
xTaskGetIdleTaskHandle（）	获取空闲任务的任务句柄
uxTaskGetStackHighWaterMark（）	获取任务的任务栈历史剩余最小值
eTaskGetState（）	获取任务状态
pcTaskGetName（）	获取任务名
xTaskGetTickCount（）	获取系统时钟节拍计数器的值
xTaskGetTickCountFromISR（）	中断中获取系统使用节拍计数器的值
xTaskGetSchedulerState（）	获取任务调度器状态
uxTaskGetNumberOfTasks（）	获取系统中任务的数量
vTaskList（）	以“表格”形式获取所有任务的信息
vTaskGetRunTimeStats（）	获取任务的运行时间等信息
vTaskSetApplicationTaskTag()	设置任务 Tag
SetThreadLocalStoragePointer()	设置任务的独有数据记录数组指针
GetThreadLocalStoragePointer()	获取任务的独有数据记录数组指针

任务相关 API 函数详解

函数 uxTaskPriorityGet()

此函数用于获取指定任务的任务优先级，若使用此函数，需在 FreeRTOSConfig.h 文件中设
置配置项 INCLUDE_uxTaskPriorityGet 为 1，此函数的函数原型如下所示：
UBaseType_t uxTaskPriorityGet(const TaskHandle_t xTask);
函数 uxTaskPriorityGet()的形参描述，如下表所示：

形参	描述
xTask	待获取优先级的任务

函数 uxTaskPriorityGet()的返回值，如下表所示：

返回值	描述
整数	指定任务的优先级

函数 vTaskPrioritySet()

此函数用于设置指定任务的优先级，若使用此函数，需在 FreeRTOSConfig.h 文件中设置配置项 INCLUDE_vTaskPrioritySet 为 1，此函数的函数原型如下所示：
void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority);
函数 vTaskPrioritySet()的形参描述，如下表所示：

形参	描述
xTask	待设置优先级的任务
uxNewPriority	任务优先级

函数 vTaskPrioritySet()无返回值

函数 uxTaskGetSystemState()

此函数用于获取所有任务的状态信息，若使用此函数，需在 FreeRTOSConfig.h 文件中设置配置项 configUSE_TRACE_FACILITY 为 1，此函数的函数原型如下所示：
UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, const UBaseType_t uxArraySize, configRUN_TIME_COUNTER_TYPE * const pulTotalRunTime);
函数 uxTaskGetSystemState()的形参描述，如下表所示：

形参	描述
pxTaskStstusArray	接收信息变量数组的首地址
uxArraySize	接收信息变量数组的大小
pilTotalRunTime	系统总运行时间

函数 uxTaskGetSystemState()的返回值，如下表所示：

返回值	描述
整型	获取信息的任务数量

注意：使用该函数会导致调度器长时间处于挂起状态， 因此该函数仅用于调试。

函数 uxTaskGetSystemState()的形参 pxTaskStatusArray 指向变量类型为 TaskStatus_t 的变量的首地址，可以是一个数组，用来存放多个TaskStatus_t类型的变量，函数 uxTaskGetSystemState()使用将任务的状态信息，写入到该数组中，形参 uxArraySize 指示该数组的大小，其中变量类型
TaskStatus_t 的定义如下所示：

typedef struct xTASK_STATUS
{
 TaskHandle_t xHandle; 							/* 任务句柄 */
 const char * pcTaskName; 						/* 任务名 */
 UBaseType_t xTaskNumber; 						/* 任务编号 */
 eTaskState eCurrentState; 						/* 任务状态 */
 UBaseType_t uxCurrentPriority; 				/* 任务优先级 */
 UBaseType_t uxBasePriority; 					/* 任务原始优先级 */
 configRUN_TIME_COUNTER_TYPE ulRunTimeCounter; 	/* 任务被分配的运行时间 */
 StackType_t * pxStackBase; 					/* 任务栈的基地址 */
 configSTACK_DEPTH_TYPE usStackHighWaterMark; 	/* 任务栈历史剩余最小值 */
} TaskStatus_t;

该结构体变量就包含了任务的一些状态信息，获取到的每个任务都有与之对应的TaskStatus_t 结构体来保存该任务的状态信息

函数 vTaskGetInfo()

此函数用于获取指定任务的任务信息，若使用此函数，需在 FreeRTOSConfig.h 文件中设置配置项 configUSE_TRACE_FACILITY 为 1，此函数的函数原型如下所示：
void vTaskGetInfo( TaskHandle_t xTask, TaskStatus_t * pxTaskStatus, BaseType_t xGetFreeStackSpace, eTaskState eState);
函数 vTaskGetInfo()的形参描述，如下表所示：

形参	描述
xTask	指定获取信息的任务
pxTaskStatus	接收任务信息的变量
xGetFreeStackSpace	任务栈历史剩余最小值
eState	任务状态

函数 vTaskGetInfo()无返回值。

注意：使用该函数会导致调度器长时间处于挂起状态， 因此该函数仅用于调试

函数 vTaskGetInfo()的形参 eState 用来表示任务的状态，其变量类型为 eTaskState，变量类型 eTaskState 的定义如下所示：

typedef enum
{
 eRunning = 0, 			/* 运行态 */
 eReady, 				/* 就绪态 */
 eBlocked, 				/* 阻塞态 */
 eSuspended, 			/* 挂起态 */
 eDeleted, 				/* 任务被删除 */
 eInvalid 				/* 非法值 */
} eTaskState;

形参 eState 用于决定形参 pxTaskStatus 结构体中成员变量 eCurrentState(任务状态) 的值，表示任务的状态，如果传入的 eState 为 eInvalid，那么 eCurrentState 为任务当前的状态，否eCurrentState为 eState。

简单来说就是如果传入的eState 是eInvalid（非法值），eCurrentState 不改变
传入的不是eInvalid 的话就更新eCurrentState 的值为eState。

函数 xTaskGetApplicationTaskTag()

此函数用于获取指定任务的 Tag，若使用此函数，需在 FreeRTOSConfig.h 文件中设置配置项 configUSE_APPLICATION_TASK_TAG 为 1，此函数的函数原型如下所示：
TaskHookFunction_t xTaskGetApplicationTaskTag(TaskHandle_t xTask);
函数 xTaskGetApplicationTaskTag()的形参描述，如下表所示：

形参	描述
xTask	待获取 Tag 的任务

函数 xTaskGetApplicationTaskTag()的返回值，如下表所示：

返回值	描述
函数指针	Tag(标签)

返回与任务关联的“标签”值。标签值的含义和用途 由应用程序编写者定义。RTOS 内核本身通常不会 访问标签值
此功能仅适用于高级用户，一般较少用到

函数 xTaskGetCurrentHandle()

此函数用于获取当前系统正在运行的 任务的任务句柄， 若使用此函数，需 在FreeRTOSConfig.h 文件中设置配置项 INCLUDE_xTaskGetCurrentTaskHandle 为 1，此函数的函数原型如下所示：
TaskHandle_t xTaskGetCurrentTaskHandle(void);
函数 xTaskGetCurrentTaskHandle()无形参
函数 xTaskGetCurrentTaskHandle()的返回值，如下表所示

返回值	描述
TaskHandle_t	任务句柄

函数 xTaskGetHandle()

此函数用于通过任务名获取任务句柄，若使用此函数，需在 FreeRTOSConfig.h 文件中设置配置项 INCLUDE_xTaskGetHandle 为 1，此函数的函数原型如下所示：
TaskHandle_t xTaskGetHandle(const char * pcNameToQuery);
函数 xTaskGetHandle()的形参描述，如下表所示：

形参	描述
pcNameToQuery	任务名

函数 xTaskGetHandle()的返回值，如下表所示：

返回值	描述
TaskHandle_t	任务句柄

函数 xTaskGetIdleTaskHandle()

此函数用于获取空闲任务的任务句柄，若使用此函数，需在 FreeRTOSConfig.h 文件中设置配置项 INCLUDE_xTaskGetIdleTaskHandle 为 1，此函数的函数原型如下所示：
TaskHandle_t xTaskGetIdleTaskHandle(void);
函数 xTaskGetIdleTaskHandle()无形参。
函数 xTaskGetIdleTaskHandle()的返回值，如下表所示：

返回值	描述
TaskHandle_t	空闲任务的任务句柄

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

函数 uxTaskGetStackHighWaterMark()

此函数用于获取指定任务的任务栈的历史剩余最小值， 若 使用此函数 ，需在FreeRTOSConfig.h 文件中设置配置项 INCLUDE_uxTaskGetStackHighWaterMark 为 1，此函数的函数原型如下所示：
UBaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask);
函数 uxTaskGetStackHighWaterMark()的形参描述，如下表所示：

形参	描述
xTask	待获取任务栈历史剩余最小值的任务

函数 uxTaskGetStackHighWaterMark()的返回值，如下表所示：

返回值	描述
整数	任务栈的历史剩余最小值

随着任务的执行和中断的处理，任务使用的堆栈会增加和缩小。 uxTaskGetStackHighWaterMark() 返回任务开始执行后任务可用的最小剩余堆栈空间量—— 即任务堆栈达到最大（最深）值时未使用的堆栈量。这就是 所谓的堆栈“高水位线”

高水位线：它返回的是任务开始执行后，任务可用的最小剩余堆栈空间量。换句话说，这个函数诉你的是：在任务执行过程中，堆栈使用量达到最大（即堆栈“最深”）时，还有多少堆栈空间是未使用的。这个未使用的堆栈空间量，就被称为堆栈的“高水位线”

如果“高水位线”的值很低，说明任务在执行过程中可能使用了大量的堆栈空间，有堆栈溢出的风险。这时，开发者就需要对任务进行优化，比如减少局部变量的使用、避免深度递归调用等。

函数 eTaskGetState()

此函数用于获取指定任务的状态，若使用此函数，需在 FreeRTOSConfig.h 文件中设置配置
项 INCLUDE_eTaskGetState 为 1，此函数的函数原型如下所示：
eTaskState eTaskGetState(TaskHandle_t xTask);
函数 eTaskGetState()的形参描述，如下表所示：

形参	描述
xTask	待获取状态的任务

函数 eTaskGetState()的返回值，如下表所示：

返回值	描述
eTaskState	任务状态

下表列出了 eTaskGetState()针对 xTask 参数引用的任务可能所处的每种状态返回的值。

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

函数 pcTaskGetName()

此函数用于获取指定任务的任务名，此函数的函数原型如下所示：
char * pcTaskGetName(TaskHandle_t xTaskToQuery);
函数 pcTaskGetName()的形参描述，如下表所示:

形参	描述
xTaskToQuery	任务句柄

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

函数 pcTaskGetName()的返回值，如下表所示：

返回值	描述
字符串	任务名

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

函数 xTaskGetTickCount()

此函数用于获取系统时钟节拍计数器的值，此函数的函数原型如下所示：
volatile TickType_t xTaskGetTickCount(void);
函数 xTaskGetTickCount()无形参

函数 xTaskGetTickCount()的返回值，如下表所示

返回值	描述
整型	系统时钟节拍计数器的值

注意 返回值自调用 vTaskStartScheduler 以来的滴答数

函数 xTaskGetTickCountFromISR()

此函数用于在中断中获取系统时钟节拍计数器的值，此函数的函数原型如下所示：
volatile TickType_t xTaskGetTickCountFromISR(void);
函数 xTaskGetTickCountFromISR()无形参。
函数 xTaskGetTickCountFromISR()的返回值，如下表所示：

返回值	描述
整型	系统时钟节拍计数器的值

注意 返回值自调用 vTaskStartScheduler 以来的滴答数

函数 xTaskGetSchedulerState()

此函数用于获取任务调度器的运行状态，INCLUDE_xTaskGetSchedulerState 或configUSE_TIMERS
必须在 FreeRTOSConfig.h 中设置为 1，才可使用此函数。此函数的函数原型如下所示：
BaseType_t xTaskGetSchedulerState(void);
函数 xTaskGetSchedulerState()无形参。
函数 xTaskGetSchedulerState()的返回值，如下表所示：

返回值	描述
整型	任务调度器的运行状态

以下任一常量（在 task.h 中定义）：askSCHEDULER_NOT_STARTED、taskSCHEDULER_RUNNING、taskSCHEDULER_SUSPENDED

函数 uxTaskGetNumberOfTasks()

此函数用于获取系统中任务的数量，此函数的函数原型如下所示：
UBaseType_t uxTaskGetNumberOfTasks(void);
函数 uxTaskGetNumberOfTasks()无形参。
函数 uxTaskGetNumberOfTasks()的返回值，如下表所示

返回值	描述
整型	任务调度器的运行状态

RTOS 内核当前正在管理的任务数。这包括所有准备就绪、阻塞和 挂起的任务。已删除但尚未被空闲任务释放的任务也将包含 在计数中。

函数 vTaskList()

此函数用于以“表格”的形式获取系统中任务的信息，若使用此函数，需在 FreeRTOSConfig.h文 件 中 同 时 设 置 配 置 项 configUSE_TRACE_FACILITY 和配置项
configUSE_STATS_FORMATTING_FUNCTIONS 为 1，此函数的函数原型如下所示：
void vTaskList(char * pcWriteBuffer);
函数 vTaskList()的形参描述，如下表所示：

形参	描述
pcWriteBuffer	接收任务信息的缓存指针

函数 vTaskList()无返回值。

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

函数 vTaskList()获取到的任务信息示例，如下图所示：

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

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

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

函数 vTaskGetRunTimeStats()

此函数用于获取指定任务的运行时间、运行状态等信息，
若使用此函数，需在
FreeRTOSConfig.h 文 件 中 同 时 设 置 配 置 项 configGENERATE_RUN_TIME_STATS、configUSE_STATS_FORMATTING_FUNCTIONS和 configSUPPORT_DYNAMIC_ALLOCATION必须定义为 1，才可使用此函数。此外，应用程序还必须提供portCONFIGURE_TIMER_FOR_RUN_TIME_STATS()和 portGET_RUN_TIME_COUNTER_VALUE
的定义，分别用于配置外设 定时器/计数器和返回定时器的当前计数值。计数器的频率应该至少是 滴答计数的 10 倍此函数的函数原型如下所示：
void vTaskGetRunTimeStats(char * pcWriteBuffer);
函数 vTaskGetRunTimeState()的形参描述，如下表所示：

形参	描述
pcWriteBuffer	接收任务运行时间和状态等信息的缓存指针

函数 vTaskGetRunTimeState()无返回值。

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

函数 vTaskSetApplicationTaskTag()

此函数用于设置指定任务的 Tag，若使用此函数，需在 FreeRTOSConfig.h 文件中设置配置项 configUSE_APPLICATION_TASK_TAG 为 1，此函数的函数原型如下所示：
void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxTagValue);
函数 vTaskSetApplicationTaskTag()的形参描述，如下表所示:

形参	描述
xTask	待插入 Tag 的任务
pxTagValue	Tag 指针

任务可以使用 NULL 作为参数值来查询自己的标签值。

函数 vTaskSetApplicationTaskTag()无返回值。

函数 SetThreadLocalStoragePointer()

此函数用于设置指定任务的独有数据数组指针，此函数的函数原型如下所示：
void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet, BaseType_t xIndex, void * pvValue)
函数 SetThreadLocalStoragePointer()的形参描述，如下表所示：

形参	描述
xTaskToSet	待设置的任务
xIndex	设置的指针
pvValue	值

函数 SetThreadLocalStoragePointer()无返回值。

函数 GetThreadLocalStoragePointer()

此函数用于获取指定任务的独有数据数组指针，此函数的函数原型如下所示
void *pvTaskGetThreadLocalStoragePointer( TaskHandle_t xTaskToQuery, BaseType_t xIndex);

函数 GetThreadLocalStoragePointer()的形参描述，如下表所示：

形参	描述
xTaskToQuery	待获取的任务
xIndex	接收的指针

函数 GetThreadLocalStoragePointer()的返回值，如下表所示：

返回值	描述
void*	指针指向的值