【freertos】FreeRTOS消息队列的介绍与使用

FreeRTOS消息队列的介绍与使用

一、概述
二、消息队列的运作机制
三、API函数
- 1、消息队列创建函数
- 2、消息队列静态创建函数
- 3、用于向队列尾部发送一个队列消息
- 4、在中断服务程序中用于向队列尾部发送一个消息
- 5、向队列队首发送一个消息
- 6、在中断服务程序中向消息队列队首发送一个消息
- 7、从一个队列中接收消息，并把接收的消息从队列中删除
- 8、在中断中从一个队列中接收消息，并从队列中删除该消息
- 9、pdMS_TO_TICKS函数使用
四、消息队列使用注意事项
五、示例代码
- 1、任务间数据传输
- 2、任务与中断间的数据传输
六、pxHigherPriorityTaskWoken
- 方式1：
- 方式2：

一、概述

$\quad$ 队列又称消息队列，是一种常用于任务间通信的数据结构，队列可以在任务与任务间、中断和任务间传递信息，实现了任务接收来自其他任务或中断的不固定长度的消息，任务能够从队列里面读取消息，当队列中的消息是空时，读取消息的任务将被阻塞，用户还可以指定阻塞的任务时间 xTicksToWait，在这段时间中，如果队列为空，该任务将保持阻塞状态以等待队列数据有效。
$\quad$ 当队列中有新消息时，被阻塞的任务会被唤醒并处理新消息；当等待的时间超过了指定的阻塞时间，即使队列中尚无有效数据，任务也会自动从阻塞态转为就绪态。
$\quad$ 消息队列是一种异步的通信方式。通过消息队列服务，任务或中断服务例程可以将一条或多条消息放入消息队列中。同样，一个或多个任务可以从消息队列中获得消息。当有多个消息发送到消息队列时，通常是将先进入消息队列的消息先传给任务，也就是说，任务先得到的是最先进入消息队列的消息，即先进先出原则（FIFO），但是也支持后进先出原则（LIFO）。
在这里插入图片描述
特性
FreeRTOS 中使用队列数据结构实现任务异步通信工作，具有如下特性：

消息支持先进先出方式排队，支持异步读写工作方式。
读写队列均支持超时机制。
消息支持后进先出方式排队，往队首发送消息（LIFO）。
可以允许不同长度（不超过队列节点最大值）的任意类型消息。
一个任务能够从任意一个消息队列接收和发送消息。
多个任务能够从同一个消息队列接收和发送消息。
当队列使用结束后，可以通过删除队列函数进行删除。

消息队列可以应用于发送不定长消息的场合，包括任务与任务间的消息交换，队列是 FreeRTOS 主要的任务间通讯方式，可以在任务与任务间、中断和任务间传送信息，发送到队列的消息是通过拷贝方式实现的，这意味着队列存储的数据是原数据，而不是原数据的引用。

二、消息队列的运作机制

$\quad$ 创建消息队列时 FreeRTOS 会先给消息队列分配一块内存空间，这块内存的大小等于消息队列控制块大小加上（单个消息空间大小与消息队列长度的乘积），接着再初始化消息队列，此时消息队列为空。FreeRTOS的消息队列控制块由多个元素组成，当消息队列被创建时，系统会为控制块分配对应的内存空间，用于保存消息队列的一些信息如消息的存储位置，头指针 pcHead、尾指针 pcTail、消息大小uxItemSize以及队列长度uxLength等。同时每个消息队列都与消息空间在同一段连续的内存空间中，在创建成功的时候，这些内存就被占用了，只有删除了消息队列的时候，这段内存才会被释放掉，创建成功的时候就已经分配好每个消息空间与消息队列的容量，无法更改，每个消息空间可以存放不大于消息大小uxItemSize的任意类型的数据，所有消息队列中的消息空间总数即是消息队列的长度，这个长度可在消息队列创建时指定。

$\quad$ 任务或者中断服务程序都可以给消息队列发送消息，当发送消息时，如果队列未满或者允许覆盖入队，FreeRTOS 会将消息拷贝到消息队列队尾，否则，会根据用户指定的阻塞超时时间进行阻塞，在这段时间中，如果队列一直不允许入队，该任务将保持阻塞状态以等待队列允许入队。当其它任务从其等待的队列中读取入了数据（队列未满），该任务将自动由阻塞态转移为就绪态。当等待的时间超过了指定的阻塞时间，即使队列中还不允许入队，任务也会自动从阻塞态转移为就绪态，此时发送消息的任务或者中断程序会收到一个错误码 errQUEUE_FULL。
$\quad$ 发送紧急消息的过程与发送消息几乎一样，唯一的不同是，当发送紧急消息时，发送的位置是消息队列队头而非队尾，这样，接收者就能够优先接收到紧急消息，从而及时进行消息处理。
$\quad$ 当某个任务试图读一个队列时，其可以指定一个阻塞超时时间。在这段时间中，如果队列为空，该任务将保持阻塞状态以等待队列数据有效。当其它任务或中断服务程序往其等待的队列中写入了数据，该任务将自动由阻塞态转移为就绪态。当等待的时间超过了指定的阻塞时间，即使队列中尚无有效数据，任务也会自动从阻塞态转移为就绪态。
$\quad$ 当消息队列不再被使用时，应该删除它以释放系统资源，一旦操作完成，消息队列将被永久性的删除。

三、API函数

1、消息队列创建函数

 QueueHandle_t xQueueCreate(UBaseType_t uxQueueLength,UBaseType_t uxItemSize);

功能描述：用于创建一个新的队列。
参数：

uxQueueLength-队列能够存储的最大消息单元数目，即队列长度。
uxItemSize-队列中消息单元的大小，以字节为单位，该大小设置非常重要，否则得到的数据不完整。

返回值：

成功-如果创建成功则返回一个队列句柄，用于访问创建的队列；
失败-如果创建不成功则返回NULL，可能原因是创建队列需要的 RAM 无法分配成功。

2、消息队列静态创建函数

QueueHandle_t xQueueCreateStatic(UBaseType_t uxQueueLength,UBaseType_t uxItemSize,uint8_t *pucQueueStorageBuffer,StaticQueue_t *pxQueueBuffer );

功能描述：用于创建一个新的队列。
参数：

uxQueueLength-队列能够存储的最大消息单元数目，即队列长度。
uxItemSize-队列中消息单元的大小，以字节为单位。
pucQueueStorageBuffer-指针，指向一个 uint8_t 类型的数组，数组的大小至少有uxQueueLength*uxItemSize 个字节。当 uxItemSize 为 0 时，pucQueueStorageBuffer 可以为 NULL。
pxQueueBuffer-指针，指向 StaticQueue_t 类型的变量，该变量用于存储队列的数据结构。

返回值：

成功-如果创建成功则返回一个队列句柄，用于访问创建的队列；
失败-如果创建不成功则返回NULL，可能原因是创建队列需要的 RAM 无法分配成功。

3、用于向队列尾部发送一个队列消息

BaseType_t xQueueSend(QueueHandle_t xQueue,const void * pvItemToQueue,TickType_t xTicksToWait);

参数说明：

xQueue-队列句柄。
pvItemToQueue-指针，指向要发送到队列尾部的队列消息。
xTicksToWait-队列满时，等待队列空闲的最大超时时间。如果队列满并且xTicksToWait 被设置成0，函数立刻返回。超时时间的单位为系统节拍周期，常量 portTICK_PERIOD_MS 用于辅助计算真实的时间，单位为 ms。如果
INCLUDE_vTaskSuspend 设置成 1，并且指定延时为 portMAX_DELAY 将导致任务挂起（没有超时）。

返回值：
$\quad$ 消息发送成功成功返回 pdTRUE，否则返回 errQUEUE_FULL。

4、在中断服务程序中用于向队列尾部发送一个消息

BaseType_t xQueueSendFromISR(QueueHandle_t xQueue,const void *pvItemToQueue,BaseType_t *pxHigherPriorityTaskWoken);

参数说明：

xQueue-队列句柄。
pvItemToQueue-指针，指向要发送到队列尾部的消息。
pxHigherPriorityTaskWoken-如果入队导致一个任务解锁，并且解锁的任务优先级高于当前被中断的任务，则将*pxHigherPriorityTaskWoken设置成pdTRUE，然后在中断退出前需要进行一次上下文切换，去执行被唤醒的优先级更高的任务，可提高实时性。从FreeRTOS V7.3.0起，pxHigherPriorityTaskWoken 作为一个可选参数，可以设置为 NULL。

返回值：
$\quad$ 消息发送成功成功返回 pdTRUE，否则返回 errQUEUE_FULL。

5、向队列队首发送一个消息

BaseType_t xQueueSendToFront( QueueHandle_t xQueue,const void * pvItemToQueue,TickType_t xTicksToWait );

参数说明：

xQueue-队列句柄。
pvItemToQueue-指针，指向要发送到队列尾部的消息。
xTicksToWait-队列满时，等待队列空闲的最大超时时间。如果队列满并且xTicksToWait 被设置成0，函数立刻返回。超时时间的单位为系统节拍周期，常量 portTICK_PERIOD_MS 用于辅助计算真实的时间，单位为 ms。如果 INCLUDE_vTaskSuspend 设置成 1，并且指定延时为 portMAX_DELAY 将导致任务无限阻塞（没有超时）。

返回值：
$\quad$ 消息发送成功成功返回 pdTRUE，否则返回 errQUEUE_FULL。

6、在中断服务程序中向消息队列队首发送一个消息

BaseType_t xQueueSendToFrontFromISR(QueueHandle_t xQueue,const void *pvItemToQueue,BaseType_t *pxHigherPriorityTaskWoken);

参数说明：

xQueue-队列句柄。
pvItemToQueue-指针，指向要发送到队首的消息。
pxHigherPriorityTaskWoken-如果入队导致一个任务解锁，并且解锁的任务优先级高于当前被中断的任务，则将*pxHigherPriorityTaskWoken设置成pdTRUE，然后在中断退出前需要进行一次上下文切换，去执行被唤醒的优先级更高的任务。从FreeRTOS V7.3.0 起，pxHigherPriorityTaskWoken 作为一个可选参数，可以设置为 NULL。

返回值：
$\quad$ 消息发送成功成功返回 pdTRUE，否则返回 errQUEUE_FULL。

7、从一个队列中接收消息，并把接收的消息从队列中删除

BaseType_t xQueueReceive(QueueHandle_t xQueue, void *pvBuffer, TickType_t xTicksToWait);

参数说明：

xQueue-队列句柄。
pvBuffer-指针，指向接收到要保存的数据。
xTicksToWait-队列空时，阻塞超时的最大时间。如果该参数设置为 0，函数立刻返回。超时时间的单位为系统节拍周期，常量portTICK_PERIOD_MS 用于辅助计算真实的时间，单位为 ms。如果 INCLUDE_vTaskSuspend 设置成1，并且指定延时为 portMAX_DELAY 将导致任务无限阻塞（没有超时）。

返回值：
$\quad$ 队列项接收成功返回 pdTRUE，否则返回 pdFALSE。

若接收完消息，不想删除，可以使用xQueuePeek函数。

8、在中断中从一个队列中接收消息，并从队列中删除该消息

BaseType_t xQueueReceiveFromISR(QueueHandle_t xQueue, void *pvBuffer, BaseType_t *pxHigherPriorityTaskWoken);

参数说明：

xQueue-队列句柄。

pvBuffer-消息

pxHigherPriorityTaskWoken-在使用之前必须初始化成
pdFALSE。如果API函数（即xQueueReceiveFromISR）导致一个任务解锁，并且解锁的任务优先级高于当前运行的任务，则API函数（即xQueueReceiveFromISR）将*pxHigherPriorityTaskWoken设置成pdTRUE。在中断退出前，触发一次任务切换。pxHigherPriorityTaskWoken作为一个可选参数，可以设置为NULL。

返回值：
$\quad$ 队列项接收成功返回 pdTRUE，否则返回 pdFALSE。

9、pdMS_TO_TICKS函数使用

const TickType_t xTicksToWait = pdMS_TO_TICKS( 100 );

宏pdMS_TO_TICKS用于将毫秒转成节拍数,FreeRTOS V8.1.0及以上版本才有这个宏。

四、消息队列使用注意事项

使用 xQueueSend()、xQueueSendFromISR()、xQueueReceive()等这些函数之前应先创建需消息队列，并根据队列句柄进行操作。
队列读取采用的是先进先出（FIFO）模式，会先读取先存储在队列中的数据。当然也 FreeRTOS 也支持后进先出（LIFO）模式，那么读取的时候就会读取到后进队列的数据。
在获取队列中的消息时候，我们必须要定义一个存储读取数据的地方，并且该数据区域大小不小于消息大小，否则，很可能引发地址非法的错误。
无论是发送或者接收消息都是以拷贝的方式进行，当然，可以通过传递指针的指针解决大数据量拷贝慢的问题，可以将消息的地址作为消息进行发送、接收（同样也会存在其它问题，例如接收任务接收到数据之前，该区域内容不得更改等）。
队列是具有自己独立权限的内核对象，并不属于任何任务。所有任务都可以向同一队列写入和读出。一个队列由多任务或中断写入是经常的事，但由多个任务读出用的比较少。

五、示例代码

1、任务间数据传输

static TaskHandle_t app_task1_handle = NULL;
static TaskHandle_t app_task2_handle = NULL;/* 任务1 */ 
static void app_task1(void* pvParameters);  /* 任务2 */  
static void app_task2(void* pvParameters); QueueHandle_t g_queue;
int main(void)
{/* 设置系统中断优先级分组4 */NVIC_PriorityGroupConfig(NVIC_PriorityGroup_4);/* 系统定时器中断频率为configTICK_RATE_HZ */SysTick_Config(SystemCoreClock/configTICK_RATE_HZ);									/* 初始化串口1 */uart_init(9600);     							/* 创建app_task1任务 */xTaskCreate((TaskFunction_t )app_task1,  		/* 任务入口函数 */(const char*    )"app_task1",			/* 任务名字 */(uint16_t       )512,  				/* 任务栈大小 */(void*          )NULL,				/* 任务入口函数参数 */(UBaseType_t    )5, 					/* 任务的优先级 */(TaskHandle_t*  )&app_task1_handle);	/* 任务控制块指针 */ /* 创建app_task2任务 */		  xTaskCreate((TaskFunction_t )app_task2,  		/* 任务入口函数 */(const char*    )"app_task2",			/* 任务名字 */(uint16_t       )512,  				/* 任务栈大小 */(void*          )NULL,				/* 任务入口函数参数 */(UBaseType_t    )5, 					/* 任务的优先级 */(TaskHandle_t*  )&app_task2_handle);	/* 任务控制块指针 */ //支持5条消息，每条消息的大小是64字节g_queue=xQueueCreate(5,64);/* 开启任务调度 */vTaskStartScheduler(); printf("none run here...\r\n");while(1);}
static void app_task1(void* pvParameters)
{char buf[64]={0};uint32_t i=0;for(;;)//while(1){printf("app_task1 is running ...\r\n");i++;sprintf(buf,"i=%d",i);//发送消息，若队列已满，只等待1秒就进行该函数当返回xQueueSend(g_queue,buf,1000);vTaskDelay(2000);}
}   static void app_task2(void* pvParameters)
{char buf[64]={0};	BaseType_t rt;for(;;)//while(1){rt = xQueueReceive(g_queue,buf,portMAX_DELAY);if(rt == pdTRUE){printf("app_task2 recv msg:%s\r\n",buf);}}
}

2、任务与中断间的数据传输

static volatile uint8_t  	g_usart1_recv_buf[64]={0};
static volatile uint32_t 	g_usart1_recv_cnt = 0;extern QueueHandle_t Test_Queue; void USART1_IRQHandler(void)
{uint8_t d;uint32_t ulReturn;BaseType_t xHigherPriorityTaskWoken;/* 进入临界段，临界段可以嵌套 */ulReturn = taskENTER_CRITICAL_FROM_ISR();	if(USART_GetITStatus(USART1, USART_IT_RXNE) != RESET)  {//接收串口数据d=USART_ReceiveData(USART1);g_usart1_recv_buf[g_usart1_recv_cnt]=d;//记录多少个数据g_usart1_recv_cnt++;//检测到'#'符或接收的数据满的时候则发送数据if(d=='#' || g_usart1_recv_cnt>=(sizeof g_usart1_recv_buf)){
#if 1xQueueSendFromISR(Test_Queue,(void *)g_usart1_recv_buf,NULL);
#elsexQueueSendFromISR(Test_Queue,(void *)g_usart1_recv_buf,&xHigherPriorityTaskWoken);
#endif			g_usart1_recv_cnt=0;}			//清空串口接收中断标志位USART_ClearITPendingBit(USART1, USART_IT_RXNE);} /* 若接收消息队列任务的优先级高于当前运行的任务，则退出中断后立即进行任务切换，执行前者;否则等待下一个时钟节拍才进行任务切换*/if( xHigherPriorityTaskWoken ){portYIELD_FROM_ISR( xHigherPriorityTaskWoken );}	/* 退出临界段 */taskEXIT_CRITICAL_FROM_ISR( ulReturn );	
}

六、pxHigherPriorityTaskWoken

pxHigherPriorityTaskWoken参数位置，作用于更高优先级任务的唤醒

BaseType_t xQueueReceiveFromISR(QueueHandle_t xQueue, void *pvBuffer, BaseType_t *pxHigherPriorityTaskWoken);

方式1：

让调度器在中断退出后，立即切换到更高优先级的等待消息队列任务。

void USART1_IRQHandler(void)   
{BaseType_t  xHigherPriorityTaskWoken = pdFALSE;......xQueueSendFromISR(g_queue_usart1,g_usart1_buf, &xHigherPriorityTaskWoken );/*  若接收消息队列任务的优先级高于被中断打断的任务，则退出中断后立即进行任务切换，执行前者;
否则等待下一个时钟节拍（≤1ms的时间）才进行任务切换*/if(xHigherPriorityTaskWoken)portYIELD_FROM_ISR( xHigherPriorityTaskWoken );......}

方式2：

让调度器在中断退出后，等待下一个时钟节拍后切换到等待消息的任务。

void USART1_IRQHandler(void)   
{....../* 在中断退出后，等待下一个时钟节拍（≤1ms的时间）才进行任务切换*/xQueueSendFromISR(g_queue_usart1,g_usart1_buf, NULL );.....}