FreeRTOS常用API接口函数

提示：FreeRTOS常用API接口函数：并对部分参数附上自己的解释,后面继续补充

---

TaskHandle_t 任务句柄的类型
XXXXType_t 都可以输入数字为uint32
函数名的前缀有2部分：返回值类型、在哪个文件定义。

1.任务相关的API

TaskHandle_t    task1；//任务句柄  表示任务
TaskHandle_t * const pxCreatedTask//    应该传入  &task1  

1.1 创建任务：xTaskCreate

BaseType_t xTaskCreate( 	TaskFunction_t pxTaskCode,//对应任务函数
                            const char * const pcName, //给任务取名字 字符串
                 			//FreeRTOS中有限制任务取名字最大长度为configMAX_TASK_NAME_LEN
                            const configSTACK_DEPTH_TYPE usStackDepth,//为该任务分配的栈大小，单位为word,10表示40字节
                            void * const pvParameters,//调用任务函数时传入的参数
                            UBaseType_t uxPriority,//任务优先级
                            TaskHandle_t * const pxCreatedTask )// 以后使用它来操作这个任务
//返回值:

1.2 开启任务调度器函数：vTaskStartScheduler

void vTaskStartScheduler( void );

1.3 任务的删除：vTaskDelete

功能：删除任务

void vTaskDelete( TaskHandle_t 任务句柄P );//删除任务句柄代表的任务
//任务句柄P来指定任务，值为NULL时，表示暂停自己。

1.3 任务的挂起：vTaskSuspend

功能：挂起任务

void vTaskSuspend( TaskHandle_t 任务句柄P );//挂起任务句柄代表的任务
//用任务句柄P来指定任务，值为NULL时，表示暂停自己。

1.3 任务的恢复：vTaskResume & xTaskResumeFromISR

功能：重新启动被Suspend（挂起）的任务

void vTaskResume( TaskHandle_t 任务句柄P );//恢复 任务句柄P代表的任务
//使用任务句柄P来指定任务，值为NULL时，表示暂停自己。

1.3获取任务的任务句柄：xTaskGetHandle

xTaskGetHandle("创建任务是取的名字：字符串")

2.优先级的API

2.1 获得任务的优先级：uxTaskPriorityGet

UBaseType_t uxTaskPriorityGet( const TaskHandle_t 任务句柄P );
//使用参数xTask来指定任务，设置为NULL表示获取自己的优先级。

2.2 设置任务的优先级：uxTaskPrioritySet

void vTaskPrioritySet( TaskHandle_t xTask,
                       UBaseType_t uxNewPriority );
//使用参数xTask来指定任务，设置为NULL表示获取自己的优先级。   
//参数uxNewPriority表示新的优先级，取值范围是0~(configMAX_PRIORITIES – 1)                

3.阻塞延迟函数

3.1 相对延迟函数:vTaskDelay

void vTaskDelay( const TickType_t xTicksToDelay ); /* xTicksToDelay: 等待多少给Tick */
//vTaskDelay(100);100个tick
//vTaskDelay(pdMS_TO_TICKS(100)); // 延迟 100 毫秒

3.2 绝对延迟函数:xTaskDelayUntil

BaseType_t xTaskDelayUntil( TickType_t * const pxPreviousWakeTime,
                            const TickType_t xTimeIncrement );
/* pxPreviousWakeTime: 上一次被唤醒的时间
 * xTimeIncrement: 要阻塞到(pxPreviousWakeTime + xTimeIncrement)
 * 单位都是Tick Count
 * vTaskDelayUntil(&preTime, 500)
 */

示例代码：需要配合 xTaskGetTickCount()使用

void LcdPrintTask(void *params)
{
	//变量的定义和初始化
	struct TaskPrintInfo *pInfo = params;
	uint32_t cnt = 0;
	int len;
	BaseType_t preTime;
	uint64_t t1, t2;
	preTime = xTaskGetTickCount();//###################关键点，第一次进入循环时候记录
	//FreeRTOS调度器启动之后，任务会在循环里面一直运行，其实调度器启动后调用过一次该任务函数，只是在频繁切换任务，任务函数从头到尾就运行过一次，为了防止任务函数停止，需要在里面加入死循环while(1){};
	//why：
	while (1)//while里面为真正的业务代码。
	{
		/* 打印信息 */
		if (g_LCDCanUse)
		{
			g_LCDCanUse = 0;
			len = LCD_PrintString(pInfo->x, pInfo->y, pInfo->name);
			len += LCD_PrintString(len, pInfo->y, ":");
			LCD_PrintSignedVal(len, pInfo->y, cnt++);
			g_LCDCanUse = 1;
			mdelay(cnt & 0x3);
		}
		
		t1 = system_get_ns();
		//vTaskDelay(500);  // 500000000
		
		vTaskDelayUntil(&preTime, 500);///关键代码
		t2 = system_get_ns();
		
		LCD_ClearLine(pInfo->x, pInfo->y+2);
		LCD_PrintSignedVal(pInfo->x, pInfo->y+2, t2-t1);
	}
}

4.队列

队列(queue)可以用于"任务到任务"、“任务到中断”、"中断到任务"直接传输信息。

4.1创建队列 xQueueCreate

QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength, UBaseType_t uxItemSize );
//uxQueueLength:队列长度，最多能存放多少个数据(item)
//uxItemSize:以字节为单位
//返回值:非0：成功，返回句柄，以后使用句柄来操作队列 NULL：失败，因为内存不足

4.1复位队列 xQueueReset

队列刚被创建时，里面没有数据；使用过程中可以调用 xQueueReset() 把队列恢复为初始状态

/*  pxQueue : 复位哪个队列;
 * 返回值: pdPASS(必定成功)
*/
BaseType_t xQueueReset( QueueHandle_t pxQueue);

4.1删除队列 xQueueDelete

删除队列的函数为 vQueueDelete() ，只能删除使用动态方法创建的队列，它会释放内存。

void vQueueDelete( QueueHandle_t xQueue );

4.1写队列

可以把数据写到队列头部，也可以写到尾部，这些函数有两个版本：在任务中使用、在ISR中使用。

4.1队列尾部写入数据：xQueueSend & xQueueSendToBackFromISR（中断）

/* 等同于xQueueSendToBack
 * 往队列尾部写入数据，如果没有空间，阻塞时间为xTicksToWait
 */
BaseType_t xQueueSend(
QueueHandle_t    xQueue,//队列句柄
const void       *pvItemToQueue,//数据指针，这个数据的值会被复制进队列， 复制多大的数据？在创建队列时已经指定了数据大小
TickType_t       xTicksToWait//如果队列满则无法写入新数据，可以让任务进入阻塞状态， xTicksToWait表示阻塞的最大时间(Tick Count)。 如果被设为0，无法写入数据时函数会立刻返回； 如果被设为portMAX_DELAY，则会一直阻塞直到有空间可写
);

/* 
 * 往队列尾部写入数据，此函数可以在中断函数中使用，不可阻塞
 */
BaseType_t xQueueSendToBackFromISR(
QueueHandle_t xQueue,//队列句柄
const void *pvItemToQueue,//数据指针，这个数据的值会被复制进队列， 复制多大的数据？在创建队列时已经指定了数据大小
BaseType_t *pxHigherPriorityTaskWoken//处中断前，是否执行比当前任务更高优先级的任务
//设置为TRUE 表示出中断时，立刻切换该函数
//设置为Flase 表示出中断时，在下一个tick处，在切换该函数
                                      
                                   );