任务相关API函数
- 任务相关API函数
- 任务相关API函数介绍
- 任务相关 API 函数详解
- 函数 uxTaskPriorityGet()
- 函数 vTaskPrioritySet()
- 函数 uxTaskGetSystemState()
- 函数 vTaskGetInfo()
- 函数 xTaskGetApplicationTaskTag()
- 函数 xTaskGetCurrentHandle()
- 函数 xTaskGetHandle()
- 函数 xTaskGetIdleTaskHandle()
- 函数 uxTaskGetStackHighWaterMark()
- 函数 eTaskGetState()
- 函数 pcTaskGetName()
- 函数 xTaskGetTickCount()
- 函数 xTaskGetTickCountFromISR()
- 函数 xTaskGetSchedulerState()
- 函数 uxTaskGetNumberOfTasks()
- 函数 vTaskList()
- 函数 vTaskGetRunTimeStats()
- 函数 vTaskSetApplicationTaskTag()
- 函数 SetThreadLocalStoragePointer()
- 函数 GetThreadLocalStoragePointer()
任务相关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,此函数的函数原型如下所示:
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* | 指针指向的值 |