FreeRTOS学习之路（二）API函数

什么是API函数

API（Application Programming Interface）是实时操作系统RTOS的应用程序接口，是已经封装好的，在程序中通过调用API函数可以快速执行相应的任务。

任务的创建和删除API函数

xTaskCreate()

使用动态的方法创建一个函数，任务的状态信息即任务控制块（TCB）需要RAM来报错，使用此函数会自动从FreeRTOS的堆中分配所需的RAM，因此需要提供内存管理文件，heap_x.c（ x = 1，2，3，4，5）。而且宏configSUPPORT_DYNAMIC_ALLOCATION必须为1。
xTaskCreate()原型

BaseType_t xTaskCreate( TaskFunction_t pxTaskCode,//任务函数
			const char * const pcName,//任务名字，长度不能超过configMAX_TASK_NAME_LEN
			const uint16_t usStackDepth,//任务堆栈大小
			void * const pvParameters,//传递给任务函数的参数
			UBaseType_t uxPriority,//任务优先级，0~configMAX_PRIORITIES-1
			TaskHandle_t * const pxCreatedTask//任务句柄，也是任务的堆栈，其他APU函数可能会使用到这个句柄）

返回值：pdPASS：任务创建成功
errCOULD_NOT_ALLOCATTE_REQUIRED_MEMORY：任务创建是吧因为堆内存不足。

xTaskCreateStatic()

使用静态的方法创建一个任务。此函数创建的任务的所需的RAM由用户提供。需要将宏config_SUPPORT_STATIC_ALLOCATION定义为1。
xTaskCreateStatic()原型

TaskHandle_t xTaskCreateStatcic( TaskFunction_t pxTaskCode,//任务函数
  const char * const pcName,//任务名字，长度不能超过configMAX_TASK_NAME_LEN
  const uint16_t usStackDepth,//任务堆栈大小
  void * const pvParameters,//传递给任务函数的参数
  UBaseType_t uxPriority,//任务优先级，0~configMAX_PRIORITIES-1
  StackType_t * const puxStackBuffer,//任务堆栈，一般为数组
  StaticTask_t * const pxTaskBuffer;)//任务控制块（TCB）

返回值：
NULL：任务创建失败，puxStackBuffer或pxTaskBuffer为NULL时会发生这个错误。
其他值：任务创建成功，返回任务的任务句柄。

xTaskCreateRestricted()

创建一个使用MPU进行限制的任务，相关内存使用动态内存分配。此函数用到比较少，不详细展开讲。

vTaskDelete()

删除一个任务。删除的任务不复存在即再也不会进入运行态。由内核分配给任务的内存才会在任务被删除之后在空闲任务中被释放掉，用户分配给任务的内存需要用户自行释放掉，调用vPortFree()将内存释放掉，否则会导致内存泄漏。
vTaskDelete()原型

cTaskDelete(TaskHandle_t xTaskTODelete)

xTaskToDelete：要删除的任务的任务句柄
没有返回值

FreeRTOS系统内核控制函数。

内核控制函数预览

taskYIELD()

此函数用于进行任务切换。

taskENTER_CRITICAL()

用于任务函数中，进入临界区。临界区就是无法被其他程序打断的区域，能保证在临界区里面的函数顺利进行。

taskEXIT_CRITICAL()

用于任务函数中，退出临界区。

taskENTER_CRITICAL_FROM_ISP()

用于中断服务函数中，进入临界区。

taskEXIT_CRITICAL_FROM)ISP()

用于中断服务函数中，退出临界区。

taskDISABLE_INTERRUPTS()

关闭可屏蔽的中断。

taskENABLE_INTERRUPTS()

打开可屏蔽的中断。

vTaskStartScheduler()

启动任务调度器。

vTaskEndScheduler()

关闭任务调度器

vTaskSuspendAll()

挂起任务调度器。

xTaskResumeAll()

将任务调度器从挂起状态恢复。

vTaskStepTick()

此函数在使用FreeRTOS的低功耗tickless模式的时候会用到，即宏configUSE_TICKLESS_IDLE为1。当使能低功耗tickless模式以后，则在执行空闲任务的时候系统时钟节拍中断就会停止运行，系统时钟中断停止运行的这段时间必须补上，这就由vTaskStepTick()来完成的。

任务的API辅助函数

辅助API函数预览表

uxTaskPriorityGet()

此函数用来获取指定任务的优先级，宏INCLUDE_uxTaskPriorityGet需要定义为1。

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

vTaskPrioritySet()

改变一个任务的优先级，宏INCLUDE_vTaskPrioritySet应该定义为1。

void vTaskPrioritySet(TaskHandle_t xTask,//任务句柄
UBaseType_t uxNewPriority)//任务要使用的新优先级，0~configMAX_PRIORITIES-1

无返回值

uxTaskGetSystemState()

获取系统中所有任务的任务状态。每个任务的状态信息保存在一个TaskStatus_t类型的结构体里面，包含任务的任务句柄、任务名字、堆栈、优先级等信息。宏configUSE_TRACE_FACILITY应该定义为1。

UBaseType_t uxTaskGetSystemState(TaskStatus_t * const pxTaskStatusArray,//指向TaskStatus_t的结构体类型的数组首地址
const UBaseType_t uxArraySize,//任务的数量，可以用函数uxTaskGetNumberOfTasks()获得
uint32_t * const pulTotalRunTime)//如果宏configGENERATE_RUN_TIME_STATS为1，则此参数用来保存系统总的运行时间。

返回值：统计到的任务个数填写到数组pxTaskStatusArray中。如果参数uxArraySize太小，则返回值可能为0。
接下来看看结构体TaskStatus_t的定义

typedef struct xTASK_STATUS
{
	TaskHandle_t xHandle;//任务句柄
	const char * pcTaskName;//任务名字
	UBaseType_t xTaskNumber;//任务编号
	eTaskState eCurrentState;//当前任务状态，枚举类型
	UBaseType_t uxCurrentPriority;//任务当前优先级
	uint32)t ulRunTimeCounter;//任务运行的总时间
	StackType_t * pxStackBase;//堆栈基地址
	uint16_t usStackHighWaterMark;//从认为创建以来任务堆栈剩余的最小值，此值太小则堆栈由溢出的风险
}TaskStatu_t;

vTaskGetInfo()

获取指定单个任务的状态，任务的状态信息填充到参数pxTaskStatus中，宏configUSE_TRACE_FACILITY要定义为1。

void vTaskGetInfo(TaskHandle_t xTask,//任务句柄
TaskStatus_t * pxTaskStatus,//类型为TaskStatu_t的结构体变量
BaseType_t xGetFreeStackSpace,//计算堆栈剩余的历史最小值，一般设为pdFALSE跳过这个步骤
eTaskState eState)//枚举类型

获取任务运行状态会耗费不少时间，eState可以直接复制，若设置为eInvalid则任务的信息就有函数vTaskGetInfo()去想办法获取。接下来看看eTaskState结构体

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

xTaskGetApplicationTaskTag()

获取任务的标签（tag）值，任务控制块（TCB）中有关pxTaskTag用来保存任务的标签值。宏configUSE_APPLICATION_TASK_TAG必须为1。

TaskHookFunction_t xTaskGetApplicationTaskTag(TaskHandle_t xTask)
//xTask:任务句柄，如果为NULL，则获取当前正在运行的任务标签值
返回值：任务的标签值

xTaskGetCurrentTaskHandle()

获取当前任务的任务句柄，宏INCLUDE_xTaskGetCurrentTaskHandle应该为1。

TaskHandle_t xTaskGetCurrentTaskHandle(void)
//没有参数

返回值：返回当前任务的任务句柄。

xTaskGetHandle()

获取任务的任务句柄，宏INCLUDE_xTaskGetHandle应该设置为1.

TaskHandle_t xTaskGetHandle(const char * pcNameToQuery)//任务名，C语言字符串

返回值：
NULL：没有任务名pcNameToQuery所对应的任务
其他值：任务名pcNameToQuery所对应的任务句柄

pcTaskGetName()

根据某个任务的任务句柄来查询这个任务对应的任务名。

char * pcTaskGetName(TaskHandle_t xTaskToQuery)//参数为要查询的任务的任务句柄

返回值：返回任务的任务名

xTaskGetSchedulerState()

此函数用于获取FreeRTOS的任务调度器运行情况：运行、关闭、挂起。宏INCLUDE_xTaskGetSchedulerState必须为1。

BaseType_t xTaskGetSchedulerState(void)

返回值：
taskSCHEDULER_NOT_STARTED:调度器为启动
taskSCHEDULER_RUNNING:调度器正在运行
taskSCHEDULER_SUSPENDED:调度器挂起

uxTaskGetNumberOfTasks()

此函数用于查询系统当前存在的任务数量。

UbaseType——t uxTaskGetNumberOfTasks(void)

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

xTaskGetIdleTaskHandle()

返回空闲任务的任务句柄。宏INCLUDE_xTaskGetIdleTaskHandle必须为1。

TaskHandle_t xTaskGetIdleTaskHandle(void)

uxTaskGetStackHighWaterMark()

每个任务的堆栈总大小在创建任务的时候就确定了，此函数用于检查任务从创建以来的堆栈的历史剩余最小值，这个值越小，说明任务堆栈溢出的可能性就越大。FreeRTOS把这个历史剩余最小值叫“高水位线”。在代码调试阶段可以使用。宏INCLUDE_uxTaskGetStackHighWaterMark必须为1。

UbaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask)//参数为要查询的任务的任务句柄，这个参数为NULL则说明查询自身任务。

返回值：任务堆栈的“高水位线”值，也就是堆栈的历史最小值。

eTaskGetState()

此函数用于查询某个任务的运行状态，返回值是个枚举类型。宏INCLUDE_eTaskGetState必须为1。

eTaskState eTaskGetState(TaskHandle_t xTask)//参数为要查询的任务的任务句柄

返回值：返回值为eTaskState枚举类型。

vTaskList()

此函数会创建一个表格来描述每个任务的详细信息。

void vTaskList(char * pcWriteBuffer)
//pcWriteBuffer:保存任务状态信息表的储存区，须足够大
无返回值。

vTaskGetRunTimeStats()

此函数用来获取任务的运行时间。宏configGENERATE_RUN_TIME_STATS和configUE_STATS_FORMATTING_FUNCTIONS都必须为1。
如果宏configGENERATE_RUN_TIME_STATS为1，还需要实现几个宏定义：

portCONFIGURE_TIMER_FOR_RUN_TIME_STATS()

此宏用来初始化一个外设，使其提供时间统计功能所需的时基，一般是定时器提供，这个时基的频率一定要比FreeRTOS的系统时钟高，系统时钟是1000Hz，周期是1ms，uoyi将定时器中断频率设置为20kHz，周期是50us，刚好是系统时钟频率的20倍。

portGET_RUN_TIME_COUNTER_VALUE()或者portALT_GET_RUN_TIME_COUNTER_VALUE(Time)

这两个宏实现其中一个就行。

void vTaskGetRunTimeStats(char * pcWriteBuffer)
//参数：pcWriteBuffer须足够大

无返回值。