STM32F1+HAL库+FreeTOTS学习10——任务相关API函数使用
- 任务相关API函数
- 1. uxTaskPriorityGet()
- 2. vTaskPrioritySet()
- 3. uxTaskGetNumberOfTasks()
- 4. uxTaskGetSystemState()
- 5. vTaskGetInfo()
- 6. xTaskGetCurrentHandle()
- 7. xTaskGetHandle()
- 8. xTaskGetIdleTaskHandle()
- 9. uxTaskGetStackHighWaterMark()
- 10. eTaskGetState()
- 11. vTaskList()
- 12. 其他
上一期,我们学习了任务切换的底层原理,这一期我们开始学习FreeRTOS任务相关API函数。
任务相关API函数
在FreeRTOS官方提供的技术文档中,把任务相关的API函数分为以下三种:
- 任务创建相关:这个我们在前面的章节有学习过,所以这里不做介绍,感兴趣的可以去看一下: STM32F1+HAL库+FreeTOTS学习3——任务创建(动态和静态两种)
- 任务控制:
3. 任务实用程序:
可以看到FreeRTOS中提供了很多的任务相关API函数,感兴趣的可以自己需官网上看一下,我们这里只列举几个出来做介绍,下面式FreeRTOS的官网:
https://www.freertos.org/zh-cn-cmn-s/Documentation/02-Kernel/04-API-references/01-Task-creation/00-TaskHandle
为了避免本篇的篇幅过长,下面所有的API函数使用都是基于如下代码,并编写在task2当中:
/* TASK1 任务 配置
* 包括: 任务句柄 任务优先级 堆栈大小
*/
#define TASK1_PRIO 1 /* 任务优先级 */
#define TASK1_STK_SIZE 128 /* 任务堆栈大小 */
TaskHandle_t Task1Task_Handler; /* 任务句柄 */
void task1(void *pvParameters); /*任务函数*/
/* TASK2 任务 配置
* 包括: 任务句柄 任务优先级 堆栈大小
*/
#define TASK2_PRIO 2 /* 任务优先级 */
#define TASK2_STK_SIZE 128 /* 任务堆栈大小 */
TaskHandle_t Task2Task_Handler; /* 任务句柄 */
void task2(void *pvParameters); /*任务函数*/
/******************************************************************************************************/
/**
* @brief FreeRTOS例程入口函数
* @param 无
* @retval 无
*/
void freertos_demo(void)
{
taskENTER_CRITICAL(); /* 进入临界区,关闭中断,此时停止任务调度*/
/* 创建任务1 */
xTaskCreate((TaskFunction_t )task1,
(const char* )"task1",
(uint16_t )TASK1_STK_SIZE,
(void* )NULL,
(UBaseType_t )TASK1_PRIO,
(TaskHandle_t* )&Task1Task_Handler);
/* 创建任务2 */
xTaskCreate((TaskFunction_t )task2,
(const char* )"task2",
(uint16_t )TASK2_STK_SIZE,
(void* )NULL,
(UBaseType_t )TASK2_PRIO,
(TaskHandle_t* )&Task2Task_Handler);
taskEXIT_CRITICAL(); /* 退出临界区,重新开启中断,开启任务调度 */
vTaskStartScheduler(); //开启任务调度
}
/**
* @brief task1
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task1(void *pvParameters)
{
while(1)
{
HAL_GPIO_TogglePin(LED0_GPIO_Port,LED0_Pin);
/* LED0闪烁 */
vTaskDelay(1000); /* 延时1000ticks */
}
}
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
while(1)
{
}
}
1. uxTaskPriorityGet()
此函数用于获取指定任务的优先级,需要把宏 INCLUDE_uxTaskPriorityGet 配置为1,函数原型如下:
/**
* @brief uxTaskPriorityGet
* @param xTask: 需要获取优先级的任务句柄,当 xTask 为NULL是,返回当前任务的优先级
* @retval 获取任务的优先级
*/
UBaseType_t uxTaskPriorityGet(const TaskHandle_t xTask);
//使用示例如下:
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
UBaseType_t taskPriority = 0;
taskPriority = uxTaskPriorityGet(NULL);
printf("任务2的优先级为:%d\r\n",taskPriority);
taskPriority = uxTaskPriorityGet(Task1Task_Handler);
printf("任务1的优先级为:%d\r\n",taskPriority);
while(1)
{
}
}
结果如下:
2. vTaskPrioritySet()
此函数用于设置指定任务的优先级,使用需要将宏 INCLUDE_vTaskPrioritySet 配置为1。函数原型如下:
/**
* @brief vTaskPrioritySet
* @param1 xTask: 需要设置优先级的任务句柄,当 xTask 为NULL是,默认设置当前任务优先级
* @param2 uxNewPriority:需要设置的优先级
* @retval 无
*/
void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority);
//使用示例如下:
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
UBaseType_t taskPriority = 0;
UBaseType_t taskPrioritySet = 5;
taskPriority = uxTaskPriorityGet(Task1Task_Handler); //查询优先级
printf("任务1的优先级为:%d\r\n",taskPriority);
vTaskPrioritySet(Task1Task_Handler,taskPrioritySet); //设置优先级
printf("设置任务1的优先级为:%d\r\n",taskPrioritySet);
taskPriority = uxTaskPriorityGet(Task1Task_Handler); //查询优先级
printf("任务1的优先级为:%d\r\n",taskPriority);
taskPriority = uxTaskPriorityGet(NULL); //流程同上
printf("任务2的优先级为:%d\r\n",taskPriority);
vTaskPrioritySet(NULL,taskPrioritySet);
printf("设置任务2的优先级为:%d\r\n",taskPrioritySet);
taskPriority = uxTaskPriorityGet(NULL);
printf("任务2的优先级为:%d\r\n",taskPriority);
while(1)
{
}
}
结果如下:
3. uxTaskGetNumberOfTasks()
此函数用于获取系统中任务的数量,此函数的函数原型如下所示:
/**
* @brief uxTaskGetNumberOfTasks
* @param 无
* @retval 系统中任务的数量
*/
UBaseType_t uxTaskGetNumberOfTasks(void);
//使用示例如下:
/**
* @brief task1
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task1(void *pvParameters)
{
while(1)
{
HAL_GPIO_TogglePin(LED0_GPIO_Port,LED0_Pin);
/* LED0闪烁 */
vTaskDelay(1000); /* 延时1000ticks */
}
}
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
UBaseType_t taskNumber = 0;
taskNumber = uxTaskGetNumberOfTasks();
printf("系统中任务的数量为%d \r\n",taskNumber); //task1、task2、空闲任务、软件定时器任务
while(1)
{
}
}
结果如下:
4. uxTaskGetSystemState()
此函数用于获取所有任务的状态信息,使用前需要将宏 configUSE_TRACE_FACILITY 配置为1,函数原型如下:
/**
* @brief uxTaskGetSystemState
* @param1 pxTaskStatusArray: 接收信息变量数组的首地址
* @param2 uxArraySize:接收信息变量数组的大小
* @param3 pulTotalRunTime:系统总运行时间,如果参数为NULL,则省略运行总时间
* @retval 获取信息的任务数量
*/
UBaseType_t uxTaskGetSystemState(
TaskStatus_t * const pxTaskStatusArray,
const UBaseType_t uxArraySize,
configRUN_TIME_COUNTER_TYPE * const pulTotalRunTime);
函数 uxTaskGetSystemState()的形参 pxTaskStatusArray 指向变量类型为 TaskStatus_t 的变量的首地址,可以是一个数组,用来存放多个TaskStatus_t类型的变量,函数 uxTaskGetSystemState()使用将任务的状态信息,写入到该数组中,形参 uxArraySize 指示该数组的大小,其中变量类型TaskStatus_t 的定义如下所示:
/*
该结构体变量就包含了任务的一些状态信息,获取到的每个任务都有与之对应的TaskStatus_t 结构体来保存该任务的状态信息。
*/
typedef struct xTASK_STATUS
{
TaskHandle_t xHandle; /* 任务句柄 */
const char * pcTaskName; /* 任务名 */
UBaseType_t xTaskNumber; /* 任务编号 */
eTaskState eCurrentState; /* 任务状态 */
UBaseType_t uxCurrentPriority; /* 任务优先级 */
UBaseType_t uxBasePriority; /* 任务原始优先级 */
configRUN_TIME_COUNTER_TYPE ulRunTimeCounter; /* 任务被分配的运行时间 */
StackType_t * pxStackBase; /* 任务栈的基地址 */
configSTACK_DEPTH_TYPE usStackHighWaterMark; /* 任务栈历史剩余最小值 */
} TaskStatus_t;
下面是使用示例:
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
TaskStatus_t * TaskStateArray = NULL; //定义信息变量数组指针(首地址)
UBaseType_t TaskNumber = uxTaskGetNumberOfTasks(); //定义总任务数量,task1、task2、空闲任务、软件定时器任务
uint8_t i =0; //定义循环变量
TaskStateArray = pvPortMalloc(sizeof(TaskStatus_t) * TaskNumber); //计算信息变量数组大小
TaskNumber = uxTaskGetSystemState( TaskStateArray, TaskNumber, NULL ); //查询所有任务信息
for(i=0;i<TaskNumber;i++) //循环打印所有任务信息
{
printf("任务名称:%s\r\n",TaskStateArray[i].pcTaskName );
printf("任务编号:%d\r\n",TaskStateArray[i].xTaskNumber);
printf("任务优先级:%d\r\n",TaskStateArray[i].uxCurrentPriority);
printf("\r\n");
}
while(1)
{
}
}
运行结果如下:
5. vTaskGetInfo()
此函数用于获取指定任务的任务信息,使用此函数,需要将宏 configUSE_TRACE_FACILITY 配置为1.函数原型如下:
/**
* @brief vTaskGetInfo
* @param1 xTask: 需要获取信息的任务句柄
* @param2 pxTaskStatus:接收任务信息的变量
* @param3 xGetFreeStackSpace:历史剩余堆栈最小值,当传入pdTRUE时检查历史剩余最小堆栈,当传入为pdFALSE时跳过这个步骤
* @param4 eState:可直接赋值,如想获取代入“eInvalid”
* @retval 无
*/
void vTaskGetInfo(
TaskHandle_t xTask,
TaskStatus_t * pxTaskStatus,
BaseType_t xGetFreeStackSpace,
eTaskState eState);
- 形参 pxTaskStatus 用来表示任务信息的变量,该结构体在 uxTaskGetSystemState()函数中有介绍,这里不做不展示
- 形参 eState 用来表示任务的状态,其变量类型为 eTaskState,变量类型 eTaskState 的定义如下所示:
typedef enum
{
eRunning = 0, /* 运行态 */
eReady, /* 就绪态 */
eBlocked, /* 阻塞态 */
eSuspended, /* 挂起态 */
eDeleted, /* 任务被删除 */
eInvalid /* 非法值 */
} eTaskState;
下面是使用示例:
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
TaskStatus_t Task1State ; //创建任务1信息变量
vTaskGetInfo( Task1Task_Handler,&Task1State,pdTRUE,eInvalid); //查询任务1的信息
printf("任务名称:%s\r\n",Task1State.pcTaskName ); //打印任务1的信息
printf("任务编号:%d\r\n",Task1State.xTaskNumber);
printf("任务优先级:%d\r\n",Task1State.uxCurrentPriority);
printf("任务历史堆栈最小值:%d\r\n",Task1State.usStackHighWaterMark);
printf("任务状态:%d\r\n",Task1State.eCurrentState);
printf("\r\n");
TaskStatus_t * Task2State = pvPortMalloc(sizeof(TaskStatus_t)); //创建任务2信息变量指针
vTaskGetInfo( Task2Task_Handler,Task2State,pdTRUE,eInvalid); //查询任务2的信息
printf("任务名称:%s\r\n",Task2State->pcTaskName ); //打印任务2的信息
printf("任务编号:%d\r\n",Task2State->xTaskNumber);
printf("任务优先级:%d\r\n",Task2State->uxCurrentPriority);
printf("任务历史堆栈最小值:%d\r\n",Task2State->usStackHighWaterMark);
printf("任务状态:%d\r\n",Task2State->eCurrentState);
while(1)
{
}
}
运行结果如下:
6. xTaskGetCurrentHandle()
此函数用于获取当前 系统正在运行的 任务的任务句柄,使用此函数,需要将宏 INCLUDE_xTaskGetCurrentTaskHandle 配置为1.函数原型如下:
/**
* @brief xTaskGetCurrentTaskHandle
* @param1 无
* @retval 当前正在运行任务的句柄
*/
TaskHandle_t xTaskGetCurrentTaskHandle(void);
下面是使用示例:
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
TaskHandle_t CurrentHandle = xTaskGetCurrentTaskHandle(); //获取正在运行任务的任务句柄
printf("任务2的任务句柄:\t%#x\r\n",Task2Task_Handler); //打印任务2的任务句柄
printf("当前正在运行的任务句柄:%#x\r\n",CurrentHandle); //打印当前任务的任务句柄
while(1)
{
}
}
运行结果如下:
7. xTaskGetHandle()
此函数用于通过任务名获取任务句柄 , 使用该函数需将宏 INCLUDE_xTaskGetHandle 置 1,函数原型如下:
/**
* @brief xTaskGetCurrentTaskHandle
* @param1 pcNameToQuery:任务名
* @retval 返回的任务句柄
*/
TaskHandle_t xTaskGetHandle(const char * pcNameToQuery);
下面是使用示例:
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
TaskHandle_t TaskHandle = xTaskGetHandle((const char* )"task1"); //获取任务1的任务句柄
printf("任务1的任务句柄:\t%#x\r\n",TaskHandle); //打印任务1的任务句柄
while(1)
{
}
}
运行结果如下:
8. xTaskGetIdleTaskHandle()
此函数用于获取空闲任务的任务句柄,若使用此函数,需将宏 INCLUDE_xTaskGetIdleTaskHandle 配置为 1,函数原型如下:
/**
* @brief xTaskGetIdleTaskHandle
* @param1 无
* @retval 空闲任务的任务句柄
*/
TaskHandle_t xTaskGetIdleTaskHandle(void);
下面是使用示例
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
TaskHandle_t IdleTaskHandle = xTaskGetIdleTaskHandle(); //获取空闲函数的任务句柄
printf("任务1的任务句柄:\t%#x\r\n",IdleTaskHandle); //打印空闲函数的任务句柄
while(1)
{
}
}
运行结果如下
9. uxTaskGetStackHighWaterMark()
此函数用于获取指定任务的任务栈历史最小剩余堆栈,使用该函数需将宏 INCLUDE_uxTaskGetStackHighWaterMark 置 1,函数原型如下:
/**
* @brief uxTaskGetStackHighWaterMark
* @param1 xTask:待获取任务栈历史剩余最小值的任务
* @retval 任务栈的历史剩余最小值
*/
UBaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask);
下面是使用示例
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
UBaseType_t TaskFreeStackSpace = uxTaskGetStackHighWaterMark(Task1Task_Handler); //获取任务1的历史堆栈最小值
printf("任务1的历史堆栈最小值:\t%d\r\n",TaskFreeStackSpace); //打印任务1的历史堆栈最小值
TaskFreeStackSpace = uxTaskGetStackHighWaterMark(Task2Task_Handler); //获取任务2的历史堆栈最小值
printf("任务2的历史堆栈最小值:\t%d\r\n",TaskFreeStackSpace); //打印任务2的历史堆栈最小值
while(1)
{
}
}
运行结果如下:
10. eTaskGetState()
此函数用于查询某个任务的运行状态,使用此函数需将宏 INCLUDE_eTaskGetState 置1,函数原型如下:
/**
* @brief eTaskGetState
* @param xTask: 待获取状态的任务
* @retval eTaskState:任务状态
*/
eTaskState eTaskGetState(TaskHandle_t xTask);
下面是使用示例:
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
eTaskState TaskState = eTaskGetState(Task1Task_Handler); //获取任务1的任务状态
printf("任务1的任务状态:\t%d\r\n",TaskState); //打印任务1的任务状态
TaskState = eTaskGetState(Task2Task_Handler); //获取任务2的任务状态
printf("任务2的任务状态:\t%d\r\n",TaskState); //打印任务2的任务状态
while(1)
{
}
}
运行结果如下:
11. vTaskList()
此函数用于以“表格”的形式获取系统中任务的信息 ,使用此函数需将宏 configUSE_TRACE_FACILITY 和configUSE_STATS_FORMATTING_FUNCTIONS 置1 ,函数原型如下:
/**
* @brief vTaskList
* @param pcWriteBuffer: 接收任务信息的缓存指针
* @retval 无
*/
void vTaskList(char * pcWriteBuffer);
下面是使用示例
char pcWriteBuffer[200]; //定义列表缓冲区
/**
* @brief task2
* @param pvParameters : 传入参数(未用到)
* @retval 无
*/
void task2(void *pvParameters)
{
vTaskList( pcWriteBuffer); //以列表的形式获取所有任务信息
printf("%s\r\n",pcWriteBuffer); //打印列表
while(1)
{
}
}
下面是运行结果
12. 其他
除上以外,FreeRTOS中还提供了很多的API函数,由于篇幅原因,这里不做过多介绍,以后用到了再记录、补充。
感兴趣的可以去官网看看:FreeRTOS官方文档