【学习FreeRTOS】第11章——FreeRTOS中任务相关的其他API函数

1.函数总览

序号	函数	描述
1	uxTaskPriorityGet()	获取任务优先级
2	vTaskPrioritySet()	设置任务优先级
3	uxTaskGetNumberOfTasks()	获取系统中任务的数量
4	uxTaskGetSystemState()	获取所有任务的状态信息
5	vTaskGetInfo()	获取单个任务的状态信息
6	xTaskGetCurrentTaskHandle()	获取当前任务的任务句柄
7	xTaskGetHandle()	获取指定任务的任务句柄
8	uxTaskGetStackHighWaterMark()	获取任务的任务栈历史剩余最小值
9	eTaskGetState()	获取任务状态
10	vTaskList()	以“表格”形式获取所有任务的信息
11	vTaskGetRunTimeStats()	获取任务的运行时间等信息
12	xTaskGetApplicationTaskTag()	获取任务Tag
13	vTaskSetApplicationTaskTag()	设置任务Tag
14	pcTaskGetName()	获取任务名
15	xTaskGetSchedulerState()	获取任务调度器状态
16	xTaskGetIdleTaskHandle()	获取空闲任务的任务句柄
17	xTaskGetTickCount()	获取系统时钟节拍计数器的值
18	xTaskGetTickCountFromISR()	中断中获取系统使用节拍计数器的值
19	GetThreadLocalStoragePointer()	获取任务的独有数据记录数组指针
20	setThreadLocalStoragePointer()	设置任务的独有数据记录数组指针

这些API函数主要用于程序调试阶段，查看任务运行状态，以及统计任务时间占比（空
闲任务占比越大，代表应用程序压力越小）
【本文只阐述一些比较重要的API，其他API可以查阅FreeRTOS官网】

2.重点函数介绍

2.1获取任务优先级

UBaseType_t  uxTaskPriorityGet(const TaskHandle_t xTask)

• 此函数用于获取指定任务的任务优先级，使用该函数需将宏 INCLUDE_uxTaskPriorityGet置1
• 形参：xTask，要查找的任务句柄（NULL代表任务自身）
• 返回值：整数，任务优先级数值

2.2.设置任务优先级

void vTaskPrioritySet(TaskHandle_t xTask, UBaseType_t uxNewPriority )

• 此函数用于改变某个任务的任务优先级，使用该函数需将宏 INCLUDE_vTaskPrioritySet置1
• 形参：xTask，任务句柄（NULL代表任务自身）；uxNewPriority，需要设置的任务优先级

2.3.获取系统中任务数量

UBaseType_t uxTaskGetNumberOfTasks(void)

• 此函数用于获取系统中任务的任务数量
• 返回值：整型，系统中任务的数量

2.4.获取所有任务的状态信息

UBaseType_t  uxTaskGetSystemState(	TaskStatus_t * const 				pxTaskStatusArray,
                                    const UBaseType_t 					uxArraySize,
                                	configRUN_TIME_COUNTER_TYPE* const 	pulTotalRunTime)
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;

• 此函数用于获取系统中所有任务的任务状态信息，使用该函数需将宏configUSE_TRACE_FACILITY置1
• 形参：xTaskStatusArray，指向TaskStatus_t 结构体数组首地址（一般要自行分配）
• 形参：uxArraySize，接收信息的数组大小（一般为任务数量）
• 形参：pulTotalRunTime，系统总运行时间，为NULL 则省略总运行时间值（一般为NULL）
• 返回值：整型，获取信息的任务数量

2.5.获取单个任务的状态信息

void vTaskGetInfo(	TaskHandle_t 	xTask, 
					TaskStatus_t* 	pxTaskStatus, 	
					BaseType_t 		xGetFreeStackSpace,
					eTaskState 		eState)
typedef enum
{   
	eRunning = 0,	/* 运行态 */ 
	eReady			/* 就绪态 */ 
	eBlocked, 		/* 阻塞态 */ 
	eSuspended, 	/* 挂起态 */ 
	eDeleted, 		/* 任务被删除 */ 
	eInvalid		/* 无效 */ 
} eTaskState;

• 此函数用于获取指定的单个任务的状态信息，使用该函数需将宏configUSE_TRACE_FACILITY置1
• 形参：xTask，指定获取信息的任务的句柄
• 形参：pxTaskStatus，接收任务信息的变量
• 形参：xGetFreeStackSpace，任务栈历史剩余最小值（当为pdFALSE跳过这个步骤，当为pdTRUE检查历史剩余最小堆栈）
• 形参：eState，任务状态，可直接赋值，如想获取代入“eInvalid”

2.6.获取当前任务的任务句柄

TaskHandle_t xTaskGetCurrentTaskHandle(void) 

• 此函数用于获取当前任务的任务句柄，使用该函数需将宏 INCLUDE_xTaskGetCurrentTaskHandle置1
• 返回值：TaskHandle_t ，当前任务的任务句柄

2.7.获取指定任务的任务句柄

TaskHandle_t xTaskGetHandle(const char* pcNameToQuery); 

• 此函数用于通过任务名获取任务句柄，使用该函数需将宏 INCLUDE_xTaskGetHandle置1
• 形参：pcNameToQuery，任务名
• 返回值：TaskHandle，任务句柄

2.8.获取任务的任务栈历史剩余最小值

UBaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask)

• 此函数用于获取指定任务的任务栈历史最小剩余堆栈，使用该函数需将宏 INCLUDE_uxTaskGetStackHighWaterMark置1
• 形参：xTask，任务句柄
• 返回值：UBaseType_t，任务栈的历史剩余最小值

2.9.获取任务状态

eTaskState    eTaskGetState(TaskHandle_t xTask)
typedef enum
{   
	eRunning = 0,	/* 运行态 */ 
	eReady			/* 就绪态 */ 
	eBlocked, 		/* 阻塞态 */ 
	eSuspended, 	/* 挂起态 */ 
	eDeleted, 		/* 任务被删除 */ 
	eInvalid		/* 无效 */ 
} eTaskState;

• 此函数用于查询某个任务的运行状态，使用此函数需将宏 INCLUDE_eTaskGetState置1
• 形参：xTask，待获取状态任务的任务句柄
• 返回值：eTaskState，任务状态

2.10.以“表格”形式获取所有任务的信息（类似于2.4获取所有任务的状态信息）

void vTaskList(char* pcWriteBuffer)

• 此函数用于以“表格”的形式获取系统中任务的信息，使用此函数需将宏 configUSE_TRACE_FACILITY、configUSE_STATS_FORMATTING_FUNCTIONS 置1
• 形参：pcWriteBuffer，接收任务信息的缓存指针

Name： 创建任务的时候给任务分配的名字。
State： 任务的壮态信息，X是运行态，B是阻塞态， R是就绪态，S是挂起态， D是删除态
Priority ：任务优先级。
Stack ： 任务堆栈的“高水位线”，就是堆栈历史最小剩余大小。
Num ： 任务编号，这个编号是唯一的，当多个任务使用同一个任务名的时候可以通过此编号来做区分。

2.11.获取任务的运行时间等信息

Void vTaskGetRunTimeStats(char * pcWriteBuffer)

• 此函数用于统计任务的运行时间信息，使用此函数需将宏 configGENERATE_RUN_TIME_STATS，configUSE_STATS_FORMATTING_FUNCTIONS 置1
• 形参：pcWriteBuffer，接收任务运行时间信息的缓存指针

Task：任务名称
Abs Time：任务实际运行的总时间（绝对时间）
% Time：占总处理时间的百分比

时间统计API函数使用流程：

1. 将宏 configGENERATE_RUN_TIME_STATS 置1
2. 将宏 configUSE_STATS_FORMATTING_FUNCTIONS 置1
3. 当将此宏 configGENERATE_RUN_TIME_STATS 置1之后，还需要实现2个宏定义：
   ① portCONFIGURE_TIMER_FOR_RUNTIME_STATE() ：用于初始化用于配置任务运行时间统计的时基定时器（该函数一般调用时基定时器的初始化，配置时间精度，这个时基定时器的计时精度需高于系统时钟节拍精度的10至100倍！）
   ② portGET_RUN_TIME_COUNTER_VALUE()：用于获取该功能时基硬件定时器计数的计数值（一般在时基函数初始化时置0，在定时器中断中自增）