FreeRTOS任务相关API函数

Posted 2023-03-09

参考技术A 1、函数 uxTaskPriorityGet()
此函数用来获取指定任务的优先级， 要使用此函数的话宏 INCLUDE_uxTaskPriorityGet 应该定义为 1， 函数原型如下：

参数：
xTask： 要查找的任务的任务句柄。
返回值： 获取到的对应的任务的优先级。
2、函数 vTaskPrioritySet()
此 函 数 用 于 改 变 某 一 个 任 务 的 任 务 优 先 级 ， 要 使 用 此 函 数 的 话 宏INCLUDE_vTaskPrioritySet 应该定义为 1，函数原型如下：

参数：
xTask： 要查找的任务的任务句柄。
uxNewPriority: 任务要使用的新的优先级， 可以是 0~ configMAX_PRIORITIES – 1。
返回值： 无。
3、 uxTaskGetSystemState()
此函数用于获取系统中所有任务的任务壮态，每个任务的壮态信息保存在一个 TaskStatus_t类型的结构体里面， 这个结构体里面包含了任务的任务句柄、任务名字、堆栈、优先级等信息，要使用此函数的话宏 configUSE_TRACE_FACILITY 应该定义为 1， 函数原型如下：

参数：
pxTaskStatusArray： 指向 TaskStatus_t 结构体类型的数组首地址，每个任务至少需要一个TaskStatus_t 结 构 体 ， 任 务 的 数 量 可 以 使 用 函 数uxTaskGetNumberOfTasks()。 结构体 TaskStatus_t 在文件 task.h 中有如下
定义：

uxArraySize: 保存任务壮态数组的数组的大小。
pulTotalRunTime: 如果 configGENERATE_RUN_TIME_STATS 为 1 的话此参数用来保存系统总的运行时间。
返回值： 统计到的任务壮态的个数，也就是填写到数组 pxTaskStatusArray 中的个
数，此值应该等于函数 uxTaskGetNumberOfTasks()的返回值。如果参数
uxArraySize 太小的话返回值可能为 0。
4、函数 vTaskGetInfo()
此函数也是用来获取任务壮态的，但是是获取指定的单个任务的壮态的，任务的壮态信息填充到参数 pxTaskStatus 中，这个参数也是 TaskStatus_t 类型的。要使用此函数的话宏configUSE_TRACE_FACILITY 要定义为 1，函数原型如下：

参数：
xTask： 要查找的任务的任务句柄。
pxTaskStatus: 指向类型为 TaskStatus_t 的结构体变量。
xGetFreeStackSpace: 在结构体 TaskStatus_t 中有个字段 usStackHighWaterMark 来保存自任务运行以来任务堆栈剩余的历史最小大小，这个值越小说明越接近堆栈溢出，但是计算这个值需要花费一点时间， 所以我们可以通过将xGetFreeStackSpace设置为pdFALSE来跳过这个步骤，当设置为pdTRUE的时候就会检查堆栈的历史剩余最小值。
eState: 结构体 TaskStatus_t 中有个字段 eCurrentState 用来保存任务运行壮态，
这个字段是 eTaskState 类型的，这是个枚举类型，在 task.h 中有如下定
义：

获取任务运行壮态会耗费不少时间，所以为了加快函数 vTaskGetInfo()的执行速度结构体 TaskStatus_t 中的字段 eCurrentState 就可以由用户直接赋值，参数 eState 就是要赋的值。如果不在乎这点时间，那么可以将 eState 设置为eInvalid，这样任务的壮态信息就由函数 vTaskGetInfo()去想办法获取。
返回值： 无
5、 函数 xTaskGetApplicationTaskTag()
此函数用于获取任务的 Tag(标签)值，任务控制块中有个成员变量 pxTaskTag 来保存任务的标签值。标签的功能由用户自行决定，此函数就是用来获取这个标签值的， FreeRTOS 系统内核是不会使用到这个标签的。要使用此函数的话宏 configUSE_APPLICATION_TASK_TAG 必须为1，函数原型如下：

参数：
xTask： 要获取标签值的任务对应的任务句柄，如果为 NULL 的话就获取当前正在运行的任务标签值。
返回值： 任务的标签值。
6、 函数 xTaskGetCurrentTaskHandle()
此函数用于获取当前任务的任务句柄， 其实获取到的就是任务控制块，在前面讲解任务创建 函 数 的 时 候 说 过 任 务 句 柄 就 是 任 务 控 制 。 如 果 要 使 用 此 函 数 的 话 宏INCLUDE_xTaskGetCurrentTaskHandle 应该为 1，函数原型如下：

参数： 无
返回值： 当前任务的任务句柄。
7、 函数 xTaskGetHandle()
此函数根据任务名字获取任务的任务句柄，在使用函数 xTaskCreate()或 xTaskCreateStatic()创建任务的时候都会给任务分配一个任务名，函数 xTaskGetHandle()就是使用这个任务名字来查询其对应的任务句柄的。 要使用此函数的话宏 INCLUDE_xTaskGetHandle 应该设置为 1，此函数原型如下：

参数：
pcNameToQuery： 任务名， C 语言字符串。
返回值：
NULL： 没有任务名 pcNameToQuery 所对应的任务。
其他值： 任务名 pcNameToQuery 所对应的任务句柄
8、函数 xTaskGetIdleTaskHandle()
此 函 数 用 于 返 回 空 闲 任 务 的 任 务 句 柄 ， 要 使 用 此 函 数 的 话 宏INCLUDE_xTaskGetIdleTaskHandle 必须为 1，函数原型如下：

参数： 无
返回值： 空闲任务的任务句柄。
9、函数 uxTaskGetStackHighWaterMark()
每个任务都有自己的堆栈，堆栈的总大小在创建任务的时候就确定了，此函数用于检查任务从创建好到现在的历史剩余最小值， 这个值越小说明任务堆栈溢出的可能性就越大！FreeRTOS 把这个历史剩余最小值叫做“高水位线”。此函数相对来说会多耗费一点时间，所以在 代 码 调 试 阶 段 可 以 使 用 ， 产 品 发 布 的 时 候 最 好 不 要 使 用 。 要 使 用 此 函 数 的 话 宏INCLUDE_uxTaskGetStackHighWaterMark 必须为 1，此函数原型如下：

参数：
xTask： 要查询的任务的任务句柄，当这个参数为 NULL 的话说明查询自身任务(即调用函数 uxTaskGetStackHighWaterMark()的任务)的“高水位线”。
返回值： 任务堆栈的“高水位线”值，也就是堆栈的历史剩余最小值。
10、函数 eTaskGetState()
此函数用于查询某个任务的运行壮态，比如：运行态、阻塞态、挂起态、就绪态等，返回值是个枚举类型。要使用此函数的话宏 INCLUDE_eTaskGetState 必须为 1，函数原型如下：

参数：
xTask： 要查询的任务的任务句柄。
返回值： 返回值为 eTaskState 类型，这是个枚举类型，在文件 task.h 中有定义，前面讲解函数 vTaskGetInfo()的时候已经讲过了。
11、函数 pcTaskGetName()
根据某个任务的任务句柄来查询这个任务对应的任务名，函数原型如下：

参数：
xTaskToQuery： 要查询的任务的任务句柄，此参数为 NULL 的话表示查询自身任务(调
用函数 pcTaskGetName())的任务名字
返回值： 返回任务所对应的任务名。
12、函数 xTaskGetTickCount()
此函数用于查询任务调度器从启动到现在时间计数器 xTickCount 的值。 xTickCount 是系统的时钟节拍值，并不是真实的时间值。 每个滴答定时器中断 xTickCount 就会加 1， 一秒钟滴答定时器中断多少次取决于宏 configTICK_RATE_HZ。理论上 xTickCount 存在溢出的问题，但是这个溢出对于 FreeRTOS 的内核没有影响，但是如果用户的应用程序有使用到的话就要考虑溢出了。什么时候溢出取决于宏 configUSE_16_BIT_TICKS，当此宏为 1 的时候 xTixkCount 就是个 16 位的变量，当为 0 的时候就是个 32 位的变量。 函数原型如下：

参数： 无。
返回值： 时间计数器 xTickCount 的值。
13、函数 xTaskGetTickCountFromISR()
此函数是 xTaskGetTickCount()的中断级版本，用于在中断服务函数中获取时间计数器xTickCount 的值，函数原型如下：

参数： 无。
返回值： 时间计数器 xTickCount 的值。
14、 函数 xTaskGetSchedulerState()
此函数用于获取 FreeRTOS 的任务调度器运行情况：运行？关闭？还是挂起！ 要使用此函数的话宏 INCLUDE_xTaskGetSchedulerState 必须为 1，此函数原型如下：

参数： 无。
返回值：
taskSCHEDULER_NOT_STARTED： 调 度 器 未 启 动 ， 调 度 器 的 启 动 是 通 过 函 数vTaskStartScheduler() 来 完 成 ， 所 以 在 函 数vTaskStartScheduler() 未 调 用 之 前 调 用 函 数xTaskGetSchedulerState()的话就会返回此值。
taskSCHEDULER_RUNNING： 调度器正在运行。
taskSCHEDULER_SUSPENDED： 调度器挂起。
15、 函数 uxTaskGetNumberOfTasks()
此函数用于查询系统当前存在的任务数量，函数原型如下：

参数： 无。
返回值： 当前系统中存在的任务数量， 此值=挂起态的任务+阻塞态的任务+就绪态的任务+空闲任务+运行态的任务。
16、函数 vTaskList()
此函数会创建一个表格来描述每个任务的详细信息
表中的信息如下：
Name： 创建任务的时候给任务分配的名字。
State： 任务的壮态信息， B 是阻塞态， R 是就绪态， S 是挂起态， D 是删除态。
Priority：任务优先级。
Stack： 任务堆栈的“高水位线”，就是堆栈历史最小剩余大小。
Num： 任务编号，这个编号是唯一的，当多个任务使用同一个任务名的时候可以通过此
编号来做区分。
函数原型如下：

参数：
pcWriteBuffer： 保存任务壮态信息表的存储区。 存储区要足够大来保存任务状态信息表。
返回值： 无
17、 函数 vTaskGetRunTimeStats()
FreeRTOS 可以通过相关的配置来统计任务的运行时间信息， 任务的运行时间信息提供了每个任务获取到 CPU 使用权总的时间。函数 vTaskGetRunTimeStats()会将统计到的信息填充到一个表里面，表里面提供了每个任务的运行时间和其所占总时间的百分比
函 数 vTaskGetRunTimeStats() 是 一 个 很 实 用 的 函 数 ， 要 使 用 此 函 数 的 话 宏configGENERATE_RUN_TIME_STATS 和 configUSE_STATS_FORMATTING_FUNCTIONS 必须都为 1。如果宏 configGENERATE_RUN_TIME_STATS 为 1 的话还需要实现一下几个宏定义：
● portCONFIGURE_TIMER_FOR_RUN_TIME_STATS()，此宏用来初始化一个外设来提供时间统计功能所需的时基， 一般是定时器/计数器。这个时基的分辨率一定要比 FreeRTOS的系统时钟高，一般这个时基的时钟精度比系统时钟的高 10~20 倍就可以了。
● portGET_RUN_TIME_COUNTER_VALUE()或者portALT_GET_RUN_TIME_COUNTER_VALUE(Time)， 这两个宏实现其中一个就行了，这两个宏用于提供当前的时基的时间值。
函数原型如下：

参数：
pcWriteBuffer： 保存任务时间信息的存储区。存储区要足够大来保存任务时间信息。
返回值： 无
18、函数 vTaskSetApplicationTaskTag()
此函数是为高级用户准备的，此函数用于设置某个任务的标签值 ，这个标签值的具体函数和用法由用户自行决定， FreeRTOS 内核不会使用这个标签值，如果要使用此函数的话宏configUSE_APPLICATION_TASK_TAG 必须为 1， 函数原型如下：

参数：
xTask： 要设置标签值的任务，此值为 NULL 的话表示设置自身任务的标签值。
pxHookFunction： 要设置的标签值，这是一个 TaskHookFunction_t 类型的函数指针，但是也可以设置为其他值。
返回值： 无
19、函数 SetThreadLocalStoragePointer()
此函数用于设置线程本地存储指针的值，每个任务都有它自己的指针数组来作为线程本地存储，使用这些线程本地存储可以用来在任务控制块中存储一些应用信息，这些信息只属于任务 自 己 的 。 线 程 本 地 存 储 指 针 数 组 的 大 小 由 宏configNUM_THREAD_LOCAL_STORAGE_POINTERS 来决定的。如果要使用此函数的话宏configNUM_THREAD_LOCAL_STORAGE_POINTERS 不能为 0，宏的具体值是本地存储指针
数组的大小， 函数原型如下：

参数：
xTaskToSet： 要设置线程本地存储指针的任务的任务句柄，如果是 NULL 的话表示设置任务自身的线程本地存储指针。
xIndex： 要设置的线程本地存储指针数组的索引。
pvValue: 要存储的值。
返回值： 无
20、函数 GetThreadLocalStoragePointer()
此 函 数 用 于 获 取 线 程 本 地 存 储 指 针 的 值 ， 如 果 要 使 用 此 函 数 的 话 宏configNUM_THREAD_LOCAL_STORAGE_POINTERS 不能为 0，函数原型如下：

参数：
xTaskToSet： 要获取的线程本地存储指针的任务句柄，如果是 NULL 的话表示获取任务自身的线程本地存储指针。
xIndex： 要获取的线程本地存储指针数组的索引。
返回值： 获取到的线程本地存储指针的值