[uCOS/RTOS]FreeRTOS操作系统——任务查询和信息统计API函数（五）

# 前言
前面学习了FreeRTOS的任务创建、任务删除、任务挂起、任务恢复、中断管理、列表与列表项等基础的API函数，这节我们来学习辅助有关的API函数，可以更多的帮助我们调试代码。

# 一、其他API函数合集
```c
uxTaskPriorityGet() 查询某个任务的优先级。 vTaskPrioritySet() 改变某个任务的任务优先级。
uxTaskGetSystemState() 获取系统中任务状态。
vTaskGetInfo() 获取某个任务信息。
xTaskGetApplicationTaskTag() 获取某个任务的标签(Tag)值。 xTaskGetCurrentTaskHandle() 获取当前正在运行的任务的任务句柄。
xTaskGetHandle() 根据任务名字查找某个任务的句柄
xTaskGetIdleTaskHandle() 获取空闲任务的任务句柄。
uxTaskGetStackHighWaterMark()
获取任务的堆栈的历史剩余最小值，FreeRTOS 中叫做“高
水位线”
eTaskGetState() 获取某个任务的壮态，这个壮态是 eTaskState 类型。
pcTaskGetName() 获取某个任务的任务名字。
xTaskGetTickCount() 获取系统时间计数器值。
xTaskGetTickCountFromISR() 在中断服务函数中获取时间计数器值
xTaskGetSchedulerState() 获取任务调度器的壮态，开启或未开启。
uxTaskGetNumberOfTasks() 获取当前系统中存在的任务数量。
vTaskList()
以一种表格的形式输出当前系统中所有任务的详细信
息。
vTaskGetRunTimeStats() 获取每个任务的运行时间。
vTaskSetApplicationTaskTag() 设置任务标签(Tag)值。
SetThreadLocalStoragePointer() 设置线程本地存储指针
GetThreadLocalStoragePointer() 获取线程本地存储指针
```



# 二、函数详解
## 1.函数 uxTaskPriorityGet()
此函数用来获取指定任务的优先级(宏 INCLUDE_uxTaskPriorityGet 应
该定义为 1)

```c
UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask )
```
参数：
xTask： 要查找的任务的任务句柄。
返回值： 获取到的对应的任务的优先级。
![在这里插入图片描述]()
函数用起来很简单，在括号里填入要查询的句柄



## 2.函数uxTaskGetSystemState()
此函数用于获取系统中所有任务的任务壮态，每个任务的壮态信息保存在一个 TaskStatus_t
类型的结构体里面，这个结构体里面包含了任务的任务句柄、任务名字、堆栈、优先级等信息，（宏 INCLUDE_uxTaskPriorityGet 应
该定义为 1)

```c
UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray,
const UBaseType_t uxArraySize,
uint32_t * const pulTotalRunTime )
```

定义：

```c
typedef struct xTASK_STATUS
{
TaskHandle_t xHandle; //任务句柄
const char * pcTaskName; //任务名字
UBaseType_t xTaskNumber; //任务编号
eTaskState eCurrentState; //当前任务壮态，eTaskState 是一个枚举类型
UBaseType_t uxCurrentPriority; //任务当前的优先级
UBaseType_t uxBasePriority; //任务基础优先级
uint32_t ulRunTimeCounter;//任务运行的总时间
StackType_t * pxStackBase; //堆栈基地址
uint16_t usStackHighWaterMark;//从任务创建以来任务堆栈剩余的最小大小，此
//值如果太小的话说明堆栈有溢出的风险。
} TaskStatus_t;
```
参数：
pxTaskStatusArray： 指向 TaskStatus_t 结构体类型的数组首地址，每个任务至少需要一个TaskStatus_t 结 构 体 ， 任 务 的 数 量 可 以 使 用 函 数uxTaskGetNumberOfTasks()。结构体 TaskStatus_t 在文件 task.h 中有如下uxArraySize: 保存任务壮态数组的数组的大小。

pulTotalRunTime:
如果 configGENERATE_RUN_TIME_STATS 为 1 的话此参数用来保存系统总的运行时间。

返回值： 统计到的任务壮态的个数，也就是填写到数组 pxTaskStatusArray 中的个
数，此值应该等于函数 uxTaskGetNumberOfTasks()的返回值。如果参数
uxArraySize 太小的话返回值可能为 0。
?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5oiR5LiObmFubw==,size_20,color_FFFFFF,t_70,g_se,x_16)
任务编号是按创建顺序来标的，第二个一定是自动创建的空闲函数，开启任务调度器会创建第三个任务Tmr Svc，之后会从下面创建的任务顺序标注。

```c
vPortFree(StatusArray);//释放内存
```
更多的函数可以看正点原子的技术手册第11章里面有详细的解释。任务管理API函数有很多，可以帮助我们调试代码，具体的使用会在后续做项目的过程中指出。

# 三、任务运行时间统计

## 1.函数 vTaskGetRunTimeStats()
FreeRTOS 可以通过相关的配置来统计任务的运行时间信息，任务的运行时间信息提供了每个任务获取到 CPU 使用权总的时间。函数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)，这两个宏实现其中一个就行
了，这两个宏用于提供当前的时基的时间值。

```c
void vTaskGetRunTimeStats( char *pcWriteBuffer )
```
参数：
pcWriteBuffer： 保存任务时间信息的存储区。存储区要足够大来保存任务时间信息。

使用时不能用系统时钟，要使用定时器


char RunTimeInfo[400];                //保存任务运行时间
![在这里插入图片描述]()
![在这里插入图片描述]()
串口输出结果如上，该函数可以自动获取任务名、运行时间并用表格形式打印

# 总结
FreeRTOS任务管理API函数可以帮助更好调试管理代码。

来源：https://bbs.21ic.com/icview-3241730-1-1.html