十二、FreeRTOS之FreeRTOS任务相关API函数

本节需要掌握以下内容：

1，FreeRTOS任务相关API函数介绍（熟悉）

2，任务状态查询API函数实验（掌握）

3，任务时间统计API函数实验（掌握）

4，课堂总结（掌握）

一、FreeRTOS任务相关API函数介绍（熟悉）

函数	描述
uxTaskPriorityGet()	获取任务优先级
vTaskPrioritySet()	设置任务优先级
uxTaskGetNumberOfTasks()	获取系统中任务的数量
uxTaskGetSystemState()	获取所有任务状态信息
vTaskGetInfo()	获取指定单个的任务信息
xTaskGetCurrentTaskHandle()	获取当前任务的任务句柄
xTaskGetHandle()	根据任务名获取该任务的任务句柄
uxTaskGetStackHighWaterMark()	获取任务的任务栈历史剩余最小值
eTaskGetState()	获取任务状态
vTaskList()	以“表格”形式获取所有任务的信息
vTaskGetRunTimeStats()	获取任务的运行时间

学习资料可参考手册《FreeRTOS开发指南》第11章 ——“FreeRTOS其他任务API函数”

1.1 获取任务优先级函数

UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask )

此函数用于获取指定任务的任务优先级，使用该函数需将宏 INCLUDE_uxTaskPriorityGet 置

形参	描述
xTask	要查找的任务句柄，NULL代表任务自身

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

1.2 设置任务优先级函数

void vTaskPrioritySet( TaskHandle_t xTask , UBaseType_t uxNewPriority )

此函数用于改变某个任务的任务优先级，使用该函数需将宏 INCLUDE_vTaskPrioritySet 为 1

形参	描述
xTask	任务句柄，NULL代表任务自身
uxNewPriority	需要设置的任务优先级

1.3 获取系统中任务的数量函数

UBaseType_t uxTaskGetNumberOfTasks( void )

此函数用于获取系统中任务的任务数量

返回值	描述
整型	系统中任务的数量

1.4 获取所有任务状态信息

UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray,

const UBaseType_t uxArraySize,

configRUN_TIME_COUNTER_TYPE * const pulTotalRunTime )

此函数用于获取系统中所有任务的任务状态信息，使用该函数需将宏 configUSE_TRACE_FACILITY 置 1

形参	描述
xTaskStatusArray	指向TaskStatus_t 结构体数组首地址
uxArraySize	接收信息的数组大小
pulTotalRunTime	系统总运行时间，为NULL 则省略总运行时间值

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

TaskStatus_t 类型定义如下：

typedef struct xTASK_STATUS

{

    TaskHandle_t   xHandle;                         /* 任务句柄 */

    const char *    pcTaskName;                       /* 任务名 */

    UBaseType_t  xTaskNumber;                       /* 任务编号 */

    eTaskState e  CurrentState;                      /* 任务状态 */

    UBaseType_t   uxCurrentPriority;                 /* 任务优先级 */

    UBaseType_t   uxBasePriority;                   /* 任务原始优先级*/

    configRUN_TIME_COUNTER_TYPE   ulRunTimeCounter;   /* 任务运行时间*/

    StackType_t *   pxStackBase;                      /* 任务栈基地址 */

    configSTACK_DEPTH_TYPE   usStackHighWaterMark;    /* 任务栈历史剩余最小值 */

} TaskStatus_t;

1.5 获取指定单个的任务信息

void vTaskGetInfo( TaskHandle_t xTask,
TaskStatus_t * pxTaskStatus,
BaseType_t xGetFreeStackSpace,
eTaskState eState )

此函数用于获取指定的单个任务的状态信息，使用该函数需将宏 configUSE_TRACE_FACILITY 置 1

形参	描述
xTask	指定获取信息的任务的句柄
pxTaskStatus	接收任务信息的变量
xGetFreeStackSpace	任务栈历史剩余最小值，当为“pdFALSE” 则跳过这个步骤，当为“pdTRUE”则检查历史剩余最小堆栈
eState	任务状态，可直接赋值，如想获取代入“eInvalid”