基于HAL库的FREERTOS----------二.任务API函数

任务API函数览概

CUBEMX对ｆｒｅｅｒｔｏｓ做了API的封装，很多ｆｒｅｅｒｔｏｓ的函数没有封装到位，可以用原函数调用。

任务API函数分别介绍

1.uxTaskPriorityGet()
此函数用来获取指定任务的优先级，要使用此函数的话宏 INCLUDE_uxTaskPriorityGet 应
该定义为 1

uxTaskPriorityGet( TaskHandle_t xTask )
参数：
xTask： 要查找的任务的任务句柄。
返回值： 获取到的对应的任务的优先级。

2.函数 vTaskPrioritySet()
此 函 数 用 于 改 变 某 一 个 任 务 的 任 务 优 先 级 ， 要 使 用 此 函 数 的 话 宏
INCLUDE_vTaskPrioritySet 应该定义为 1

void vTaskPrioritySet( TaskHandle_t xTask, 
UBaseType_t uxNewPriority )
参数：
xTask： 要查找的任务的任务句柄。
uxNewPriority: 任务要使用的新的优先级，可以是 0~ configMAX_PRIORITIES – 1

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

根据使用要求，应当在CUBEMX中使能相应配置。此处说明，后面API函数同理，不再举例

UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray, 
const UBaseType_t uxArraySize, uint32_t * const pulTotalRunTime )
参数：
pxTaskStatusArray： 指向 TaskStatus_t 结构体类型的数组首地址，每个任务至少需要一个
TaskStatus_t 结 构 体 ， 任 务 的 数 量 可 以 使 用 函 数
uxTaskGetNumberOfTasks()。结构体 TaskStatus_t 在文件 task.h 中有如下
定义：
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;
uxArraySize: 保存任务壮态数组的数组的大小。
pulTotalRunTime: 如果 configGENERATE_RUN_TIME_STATS 为 1 的话此参数用来保存系
统总的运行时间。
返回值： 统计到的任务壮态的个数，也就是填写到数组 pxTaskStatusArray 中的个
数，此值应该等于函数 uxTaskGetNumberOfTasks()的返回值。如果参数
uxArraySize 太小的话返回值可能为 0。

４．函数 vTaskGetInfo()
此函数也是用来获取任务壮态的，但是是获取指定的单个任务的壮态的，任务的壮态信息
填充到参数 pxTaskStatus 中，这个参数也是 TaskStatus_t 类型的。要使用此函数的话宏
configUSE_TRACE_FACILITY 要定义为 1

void vTaskGetInfo( TaskHandle_t xTask, 
TaskStatus_t * pxTaskStatus, 
BaseType_t xGetFreeStackSpace, 
eTaskState eState )
参数：
xTask： 要查找的任务的任务句柄。
pxTaskStatus: 指向类型为 TaskStatus_t 的结构体变量。
xGetFreeStackSpace: 在结构体 TaskStatus_t 中有个字段 usStackHighWaterMark 来保存自任务
运行以来任务堆栈剩余的历史最小大小，这个值越小说明越接近堆栈溢
出，但是计算这个值需要花费一点时间， 所以我们可以通过将
xGetFreeStackSpace设置为pdFALSE来跳过这个步骤，当设置为pdTRUE
的时候就会检查堆栈的历史剩余最小值。
eState: 结构体 TaskStatus_t 中有个字段 eCurrentState 用来保存任务运行壮态，
这个字段是 eTaskState 类型的，这是个枚举类型，在 task.h 中有如下定
义：
typedef enum
{
eRunning = 0, //运行壮态
eReady, //就绪态
eBlocked, //阻塞态
eSuspended, //挂起态
eDeleted, //任务被删除
eInvalid //无效
} eTaskState;
获取任务运行壮态会耗费不少时间，所以为了加快函数 vTaskGetInfo()的执行
速度结构体 TaskStatus_t 中的字段 eCurrentState 就可以由用户直接赋值，
参数 eState 就是要赋的值。如果不在乎这点时间，那么可以将 eState 设置为
eInvalid，这样任务的壮态信息就由函数 vTaskGetInfo()去想办法获取。
返回值： 无

5、函数 xTaskGetApplicationTaskTag()
此函数用于获取任务的 Tag(标签)值，任务控制块中有个成员变量 pxTaskTag 来保存任务的
标签值。标签的功能由用户自行决定，此函数就是用来获取这个标签值的，FreeRTOS 系统内核
是不会使用到这个标签的。要使用此函数的话宏 configUSE_APPLICATION_TASK_TAG 必须为
1

TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask )
参数：
xTask： 要获取标签值的任务对应的任务句柄，如果为 NULL 的话就获取当前正在运
行的任务标签值。
返回值： 任务的标签值

6、函数 xTaskGetCurrentTaskHandle()
此函数用于获取当前任务的任务句柄，其实获取到的就是任务控制块，在前面讲解任务创
建 函 数 的 时 候 说 过 任 务 句 柄 就 是 任 务 控制。 如 果 要 使 用 此 函 数 的 话 宏
INCLUDE_xTaskGetCurrentTaskHandle 应该为 1

TaskHandle_t xTaskGetCurrentTaskHandle( void )
参数： 无
返回值： 当前任务的任务句柄

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

TaskHandle_t xTaskGetHandle( const char * pcNameToQuery )
参数：
pcNameToQuery： 任务名，C 语言字符串。
返回值：
NULL： 没有任务名 pcNameToQuery 所对应的任务。
其他值： 任务名 pcNameToQuery 所对应的任务句柄

8、函数 xTaskGetIdleTaskHandle()
此 函 数 用 于 返 回 空 闲 任 务 的 任 务 句 柄 ， 要 使 用 此 函 数 的 话 宏
INCLUDE_xTaskGetIdleTaskHandle 必须为 1

TaskHandle_t xTaskGetIdleTaskHandle( void )
参数： 无
返回值： 空闲任务的任务句柄。

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

UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask )
参数：
xTask： 要查询的任务的任务句柄，当这个参数为 NULL 的话说明查询自身任务(即调用
函数 uxTaskGetStackHighWaterMark()的任务)的“高水位线”。
返回值： 任务堆栈的“高水位线”值，也就是堆栈的历史剩余最小值。

10、函数 eTaskGetState()
此函数用于查询某个任务的运行壮态，比如：运行态、阻塞态、挂起态、就绪态等，返回
值是个枚举类型。要使用此函数的话宏 INCLUDE_eTaskGetState 必须为 1

eTaskState eTaskGetState( TaskHandle_t xTask )
参数：
xTask： 要查询的任务的任务句柄。
返回值： 返回值为 eTaskState 类型，这是个枚举类型，在文件 task.h 中有定义，前面讲解
函数 vTaskGetInfo()的时候已经讲过了

11、函数 pcTaskGetName()
根据某个任务的任务句柄来查询这个任务对应的任务名

char *pcTaskGetName( TaskHandle_t xTaskToQuery )
参数：
xTaskToQuery： 要查询的任务的任务句柄，此参数为 NULL 的话表示查询自身任务(调
用函数 pcTaskGetName())的任务名字
返回值： 返回任务所对应的任务名

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

TickType_t xTaskGetTickCount( void )
参数： 无。
返回值： 时间计数器 xTickCount 的值

13、函数 xTaskGetTickCountFromISR()
此函数是 xTaskGetTickCount()的中断级版本，用于在中断服务函数中获取时间计数器xTickCount 的值

TickType_t xTaskGetTickCountFromISR( void )
参数： 无。
返回值： 时间计数器 xTickCount 的值

14、函数 xTaskGetSchedulerState()
此函数用于获取 FreeRTOS 的任务调度器运行情况：运行？关闭？还是挂起！要使用此函
数的话宏 INCLUDE_xTaskGetSchedulerState 必须为 1

BaseType_t xTaskGetSchedulerState( void )
参数： 无。
返回值： 
taskSCHEDULER_NOT_STARTED： 调 度 器 未 启 动 ， 调 度 器 的 启 动 是 通 过 函 数
vTaskStartScheduler() 来完成，所以在函数
vTaskStartScheduler() 未调用之前调用函数

xTaskGetSchedulerState()的话就会返回此值。
taskSCHEDULER_RUNNING： 调度器正在运行。
taskSCHEDULER_SUSPENDED： 调度器挂起。

15、函数 uxTaskGetNumberOfTasks()
此函数用于查询系统当前存在的任务数量

UBaseType_t uxTaskGetNumberOfTasks( void )
参数： 无。
返回值： 当前系统中存在的任务数量， 此值=挂起态的任务+阻塞态的任务+就绪态的任务 
 +空闲任务+运行态的任务。

16、函数 vTaskList()
此函数会创建一个表格来描述每个任务的详细信息

void vTaskList( char * pcWriteBuffer )
参数：
pcWriteBuffer： 保存任务壮态信息表的存储区。存储区要足够大来保存任务状态信息表。
返回值： 无

17、函数 vTaskGetRunTimeStats()
FreeRTOS 可以通过相关的配置来统计任务的运行时间信息，任务的运行时间信息提供了
每个任务获取到 CPU 使用权总的时间。函数 vTaskGetRunTimeStats()会将统计到的信息填充到
一个表里面，表里面提供了每个任务的运行时间和其所占总时间的百分比，如图 11.2.2 所示：
图 11.2.2 任务运行时间表
函 数 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)，这两个宏实现其中一个就行
了，这两个宏用于提供当前的时基的时间值

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

18、函数 vTaskSetApplicationTaskTag()
此函数是为高级用户准备的，此函数用于设置某个任务的标签值 ，这个标签值的具体函数
和用法由用户自行决定，FreeRTOS 内核不会使用这个标签值，如果要使用此函数的话宏
configUSE_APPLICATION_TASK_TAG 必须为 1

void vTaskSetApplicationTaskTag( TaskHandle_t xTask, 
TaskHookFunction_t pxHookFunction )
参数：
xTask： 要设置标签值的任务，此值为 NULL 的话表示设置自身任务的标签值。
pxHookFunction： 要设置的标签值，这是一个 TaskHookFunction_t 类型的函数指针，但是
也可以设置为其他值。
返回值： 无

19、函数 SetThreadLocalStoragePointer()
此函数用于设置线程本地存储指针的值，每个任务都有它自己的指针数组来作为线程本地
存储，使用这些线程本地存储可以用来在任务控制块中存储一些应用信息，这些信息只属于任
务 自 己 的 。 线 程 本 地 存 储 指 针 数 组 的 大 小 由 宏
configNUM_THREAD_LOCAL_STORAGE_POINTERS 来决定的。如果要使用此函数的话宏
configNUM_THREAD_LOCAL_STORAGE_POINTERS 不能为 0，宏的具体值是本地存储指针
数组的大小，

void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet, 
BaseType_t xIndex, 
void * pvValue )
参数：
xTaskToSet： 要设置线程本地存储指针的任务的任务句柄，如果是 NULL 的话表示设置任
务自身的线程本地存储指针。
xIndex： 要设置的线程本地存储指针数组的索引。
pvValue: 要存储的值。
返回值： 无

20、函数 GetThreadLocalStoragePointer()
此 函 数 用 于 获 取 线 程 本 地 存 储 指 针 的 值 ， 如 果 要 使 用 此 函 数 的 话 宏
configNUM_THREAD_LOCAL_STORAGE_POINTERS 不能为 0

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

实验验证
此处验证API函数第三个，应该在CUBEMX中开启

void StartTask02(void const * argument)
{
  /* USER CODE BEGIN StartTask02 */
	
		uint32_t TotalRunTime;
		UBaseType_t ArraySize,x;
		TaskStatus_t *StatusArray;
  /* Infinite loop */
  for(;;)
  {
		
		//第一步：函数 uxTaskGetSystemState()的使用
		printf("/********第一步：函数 uxTaskGetSystemState()的使用**********/\r\n");
		ArraySize=uxTaskGetNumberOfTasks(); //获取系统任务数量 (1)
		StatusArray=pvPortMalloc(ArraySize*sizeof(TaskStatus_t)); //申请内存 (2)
		if(StatusArray!=NULL) //内存申请成功
		{
			ArraySize=uxTaskGetSystemState((TaskStatus_t* )StatusArray,// (3)
																			(UBaseType_t )ArraySize, 
																			(uint32_t* )&TotalRunTime);
			printf("TaskName\t\tPriority\t\tTaskNumber\t\t\r\n");
			for(x=0;x<ArraySize;x++)
			{
				//通过串口打印出获取到的系统任务的有关信息，比如任务名称、
				//任务优先级和任务编号。
				printf("%s\t\t%d\t\t\t%d\t\t\t\r\n", 												//(4)
								StatusArray[x].pcTaskName,
								(int)StatusArray[x].uxCurrentPriority,
								(int)StatusArray[x].xTaskNumber);
			}
		}
		vPortFree(StatusArray); //释放内存 (5)
    osDelay(1000);
  }
  /* USER CODE END StartTask02 */
}