STM32F1+HAL库+FreeTOTS学习10——任务相关API函数使用

上一期，我们学习了任务切换的底层原理，这一期我们开始学习FreeRTOS任务相关API函数。

任务相关API函数

在FreeRTOS官方提供的技术文档中，把任务相关的API函数分为以下三种：

1. 任务创建相关：这个我们在前面的章节有学习过，所以这里不做介绍，感兴趣的可以去看一下： STM32F1+HAL库+FreeTOTS学习3——任务创建（动态和静态两种）
   
2. 任务控制：
   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官方文档