STM32Cube-FreeRTOS任务管理工具函数-笔记

一、获取任务句柄的函数

1. 创建任务并获取句柄

osThreadNew() 创建任务时返回类型为 osThreadId_t。
实际上，osThreadId_t 是对 FreeRTOS 的 TaskHandle_t 类型的封装。
底层调用 xTaskCreateStatic() 或 xTaskCreate()，返回值为 TaskHandle_t。

当我们在FreeRTOS要调用osThreadNew来创建任务的时候，它会返回一个osThreadId_t这个类型的变量作为任务句柄。

os开头的类型实际上是被包装过的一个类型，这个类型是被定义在这个文件里面，它不是一个 FreeRTOS自带的这么一种类型。

实际上osThreadNew它的核心是调用了xTaskCreateStatic或者是xTaskCreate。Create state它也有一个返回的类型。

TaskHandle_t这个类型是FreeRTOS定义的一种类型，它跟我们刚才这个osThreadId_t是等价的。其实这个东西它就叫做任务的句柄。

在创建任务时就获得了一个返回的任务句柄变量。那么这个变量就可以作为FreeRTOS任务操作函数的任务句柄输入参数。除了在任务创建时获取到任务的句柄，在FreeRTOS中还有3个用于获取任务句柄的函数。

---

由于右侧的函数列表太多了，所以outline试图被禁用了。

解决函数较多，让其他函数显示出来的设置方法。

---

2. 获取当前任务句柄

获取当前任务的句柄：xTaskGetCurrentTaskHandle()
返回值的方式获取到一个任务句柄。

可以看到在这个函数之上是有两个条件。必须在我们的STM32CubeMX可视化界面中将（INCLUDE_xTaskGetCurrentTaskHandle）这个选项设置为1，这个函数才可以被参与编译。否则这个函数将会被裁剪掉，以减少我们编译出来的文件的大小。

---

3. 获取空闲任务句柄

获取空闲任务的句柄：xTaskGetIdleTaskHandle
可以发现这里有灰色的底，这个函数它在STM32CubeMX里是不能设置的。如果你需要使用这个函数，可以将（INCLUDE_xTaskGetIdleTaskHandle）这个变量底范围1，那这里就可以参与编译。

---

4. 根据任务名称获取句柄

获取任务句柄的函数：xTaskGetHandle(const char *pcNameToQuery)
函数它需要传入的参数是任务名称的字符串。这函数运行的时间比较长，不建议大量使用。如果两个任务具有相同的任务名称，那函数返回的结果是不确定的。
可以将（INCLUDE_xTaskGetHandle）这个变量底范围1，那这里就可以参与编译。

二、单个任务操作相关函数

1. 程序在运行时可以获取或改变一个任务的优先级

函数：uxTaskPriorityGet(TaskHandle_t xTask)
功能：获取指定任务的当前优先级。

1.1. uxTaskPriorityGetFromISR，是上一个函数的中断服务程序版本

3. 获取任务信息

函数： vTaskGetInfo()
使用这两个函数都需要在STM32CubeMX中确保开启了（INCLUDE_uxTaskPriorityGet）这个选项。

---

4. 获取任务信息

函数： vTaskGetInfo()

4.1. 函数作用
vTaskGetInfo() 是 FreeRTOS 中用于获取指定任务详细信息的调试函数。它可以获取任务的以下信息：

• 任务状态（如运行态、就绪态、阻塞态等）
• 任务优先级
• 任务名称
• 堆栈使用情况（可选）
• 运行时间统计（需配置宏）
• 任务句柄和编号

4.2. 函数原型

void vTaskGetInfo(TaskHandle_t xTask,          // 要查询的任务句柄TaskStatus_t *pxTaskStatus,  // 保存任务信息的结构体指针BaseType_t xGetFreeStackSpace, // 是否计算堆栈最小剩余空间eTaskState eState            // 是否获取任务当前状态
);

---

5. 获取任务名称

函数：pcTaskGetName(TaskHandle_t xTask)

功能：返回的是一个字符型的指针。它传入的参数是一个需要被查询的任务句柄。

---

6. 获取堆栈高水位值

函数：uxTaskGetStackHighWaterMark(TaskHandle_t xTask)

获取任务的高水位值的函数。这个高水位值实际上就是任务的占空间最少，可用的剩余空间大小单位是字，这个值越小表示任务的占空间越容易溢出。当发现获取到的这个值偏小的时候，就要考虑扩大这个任务的占空间。

---

7. 获取任务状态

函数：eTaskGetState(TaskHandle_t xTask)

返回任务的当前状态。以e函开头的表示，它的返回值是一个枚举型。

三、核信息统计相关的函数

1. 获取系统中任务总数

函数：uxTaskGetNumberOfTasks()

功能：返回任务当前管理的任务的总数，包括就绪和阻塞的挂起的任务，也包含虽然删除了但是没有在空闲任务里释放的。

---

2. 获取任务列表字符串

函数：vTaskList(char *pcWriteBuffer)

功能：返回内核中所有任务的字符串列表信息，包含每个任务的名称、状态、优先级、高水位值、任务编号。使用这个函数时需要传入一个足够大的字符数组，FreeRTOS不会检查这个传入的数组的大小。

注意事项：vTaskList代码中用到了sprint f函数，会使编译后的应用大小明显增大。所以说这个函数一般只在调试时使用，不要在发布版本里使用。

---

获取系统任务状态数组

函数：uxTaskGetSystemState()
参数第一个是一个数组的指针，它是一个结构体数组需要预先的分配，数组的大小必须是大于等于FreeRTOS内的任务，下一个参数是指的第一个参数中的数组的成员个数。第三个参数用于返回FreeRTOS运行后的总时间。

---

获取任务运行时间统计

函数：vTaskGetRunTimeStats(char *pcWriteBuffer)
功能：输出任务运行时间和 CPU 占比。

函数也需要传入一个字符串，会以文字表格的形式返回出每个任务的运行时间，包括绝对时间和占用CPU的百分比。需要注意的是，这个函数它在运行时会禁用掉所有中断，所以不要在程序正常运行时使用这个函数，应该只在调试阶段使用。

---

调度器当前状态

函数：xTaskGetSchedulerState()
功能：返回调度器当前状态。
返回值：
taskSCHEDULER_NOT_STARTED（未启动）
taskSCHEDULER_RUNNING（运行中）
taskSCHEDULER_SUSPENDED（被挂起）