本教程基于韦东山百问网出的 DShanMCU-F103开发板进行编写，需要的同学可以在这里获取： https://item.taobao.com/item.htm?id=724601559592

配套资料获取：https://rtos.100ask.net/zh/freeRTOS/DShanMCU-F103

freeRTOS系列教程之freeRTOS入门与工程实践章节汇总： https://blog.csdn.net/qq_35181236/article/details/132842016

第11章队列(queue)

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

本章涉及如下内容：

怎么创建、清除、删除队列
队列中消息如何保存
怎么向队列发送数据、怎么从队列读取数据、怎么覆盖队列的数据
在队列上阻塞是什么意思
怎么在多个队列上阻塞
读写队列时如何影响任务的优先级

11.1 队列的特性

1.1.1 常规操作

队列的简化操如入下图所示，从此图可知：

队列可以包含若干个数据：队列中有若干项，这被称为"长度"(length)
每个数据大小固定
创建队列时就要指定长度、数据大小
数据的操作采用先进先出的方法(FIFO，First In First Out)：写数据时放到尾部，读数据时从头部读
也可以强制写队列头部：覆盖头部数据

更详细的操作入下图所示：

11.1.2 传输数据的两种方法

使用队列传输数据时有两种方法：

拷贝：把数据、把变量的值复制进队列里
引用：把数据、把变量的地址复制进队列里

FreeRTOS使用拷贝值的方法，这更简单：

局部变量的值可以发送到队列中，后续即使函数退出、局部变量被回收，也不会影响队列中的数据
无需分配buffer来保存数据，队列中有buffer
局部变量可以马上再次使用
发送任务、接收任务解耦：接收任务不需要知道这数据是谁的、也不需要发送任务来释放数据
如果数据实在太大，你还是可以使用队列传输它的地址
队列的空间有FreeRTOS内核分配，无需任务操心
对于有内存保护功能的系统，如果队列使用引用方法，也就是使用地址，必须确保双方任务对这个地址都有访问权限。使用拷贝方法时，则无此限制：内核有足够的权限，把数据复制进队列、再把数据复制出队列。

11.1.3 队列的阻塞访问

只要知道队列的句柄，谁都可以读、写该队列。任务、ISR都可读、写队列。可以多个任务读写队列。

任务读写队列时，简单地说：如果读写不成功，则阻塞；可以指定超时时间。口语化地说，就是可以定个闹钟：如果能读写了就马上进入就绪态，否则就阻塞直到超时。

某个任务读队列时，如果队列没有数据，则该任务可以进入阻塞状态：还可以指定阻塞的时间。如果队列有数据了，则该阻塞的任务会变为就绪态。如果一直都没有数据，则时间到之后它也会进入就绪态。

既然读取队列的任务个数没有限制，那么当多个任务读取空队列时，这些任务都会进入阻塞状态：有多个任务在等待同一个队列的数据。当队列中有数据时，哪个任务会进入就绪态？

优先级最高的任务
如果大家的优先级相同，那等待时间最久的任务会进入就绪态

跟读队列类似，一个任务要写队列时，如果队列满了，该任务也可以进入阻塞状态：还可以指定阻塞的时间。如果队列有空间了，则该阻塞的任务会变为就绪态。如果一直都没有空间，则时间到之后它也会进入就绪态。

既然写队列的任务个数没有限制，那么当多个任务写"满队列"时，这些任务都会进入阻塞状态：有多个任务在等待同一个队列的空间。当队列中有空间时，哪个任务会进入就绪态？

优先级最高的任务
如果大家的优先级相同，那等待时间最久的任务会进入就绪态

11.2 队列函数

使用队列的流程：创建队列、写队列、读队列、删除队列。

11.2.1 创建

队列的创建有两种方法：动态分配内存、静态分配内存，

动态分配内存：xQueueCreate，队列的内存在函数内部动态分配

函数原型如下：

QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength, UBaseType_t uxItemSize );

参数	说明
uxQueueLength	队列长度，最多能存放多少个数据(item)
uxItemSize	每个数据(item)的大小：以字节为单位
返回值	非0：成功，返回句柄，以后使用句柄来操作队列 NULL：失败，因为内存不足

静态分配内存：xQueueCreateStatic，队列的内存要事先分配好

函数原型如下：

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

参数	说明
uxQueueLength	队列长度，最多能存放多少个数据(item)
uxItemSize	每个数据(item)的大小：以字节为单位
pucQueueStorageBuffer	如果uxItemSize非0，pucQueueStorageBuffer必须指向一个uint8_t数组，此数组大小至少为"uxQueueLength * uxItemSize"
pxQueueBuffer	必须执行一个StaticQueue_t结构体，用来保存队列的数据结构
返回值	非0：成功，返回句柄，以后使用句柄来操作队列 NULL：失败，因为pxQueueBuffer为NULL

示例代码：

// 示例代码
 #define QUEUE_LENGTH 10
 #define ITEM_SIZE sizeof( uint32_t )
 
 // xQueueBuffer用来保存队列结构体
 StaticQueue_t xQueueBuffer;

// ucQueueStorage 用来保存队列的数据

// 大小为：队列长度 * 数据大小
 uint8_t ucQueueStorage[ QUEUE_LENGTH * ITEM_SIZE ];

 void vATask( void *pvParameters )
 {
    
    
	QueueHandle_t xQueue1;

	// 创建队列: 可以容纳QUEUE_LENGTH个数据，每个数据大小是ITEM_SIZE
	xQueue1 = xQueueCreateStatic( QUEUE_LENGTH,
							ITEM_SIZE,
                            ucQueueStorage,
                            &xQueueBuffer ); 
  }

11.2.2 复位

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

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

11.2.3 删除

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

void vQueueDelete( QueueHandle_t xQueue );

11.2.4 写队列

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

/* 等同于xQueueSendToBack
 * 往队列尾部写入数据，如果没有空间，阻塞时间为xTicksToWait
 */
BaseType_t xQueueSend(
                                QueueHandle_t    xQueue,
                                const void       *pvItemToQueue,
                                TickType_t       xTicksToWait
                            );

/* 
 * 往队列尾部写入数据，如果没有空间，阻塞时间为xTicksToWait
 */
BaseType_t xQueueSendToBack(
                                QueueHandle_t    xQueue,
                                const void       *pvItemToQueue,
                                TickType_t       xTicksToWait
                            );


/* 
 * 往队列尾部写入数据，此函数可以在中断函数中使用，不可阻塞
 */
BaseType_t xQueueSendToBackFromISR(
                                      QueueHandle_t xQueue,
                                      const void *pvItemToQueue,
                                      BaseType_t *pxHigherPriorityTaskWoken
                                   );

/* 
 * 往队列头部写入数据，如果没有空间，阻塞时间为xTicksToWait
 */
BaseType_t xQueueSendToFront(
                                QueueHandle_t    xQueue,
                                const void       *pvItemToQueue,
                                TickType_t       xTicksToWait
                            );

/* 
 * 往队列头部写入数据，此函数可以在中断函数中使用，不可阻塞
 */
BaseType_t xQueueSendToFrontFromISR(
                                      QueueHandle_t xQueue,
                                      const void *pvItemToQueue,
                                      BaseType_t *pxHigherPriorityTaskWoken
                                   );

这些函数用到的参数是类似的，统一说明如下：

参数	说明
xQueue	队列句柄，要写哪个队列
pvItemToQueue	数据指针，这个数据的值会被复制进队列，复制多大的数据？在创建队列时已经指定了数据大小
xTicksToWait	如果队列满则无法写入新数据，可以让任务进入阻塞状态， xTicksToWait表示阻塞的最大时间(Tick Count)。如果被设为0，无法写入数据时函数会立刻返回；如果被设为portMAX_DELAY，则会一直阻塞直到有空间可写
返回值	pdPASS：数据成功写入了队列 errQUEUE_FULL：写入失败，因为队列满了。

11.2.5 读队列

使用**xQueueReceive()**函数读队列，读到一个数据后，队列中该数据会被移除。这个函数有两个版本：在任务中使用、在ISR中使用。函数原型如下：

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

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

参数说明如下：

参数	说明
xQueue	队列句柄，要读哪个队列
pvBuffer	bufer指针，队列的数据会被复制到这个buffer 复制多大的数据？在创建队列时已经指定了数据大小
xTicksToWait	果队列空则无法读出数据，可以让任务进入阻塞状态， xTicksToWait表示阻塞的最大时间(Tick Count)。如果被设为0，无法读出数据时函数会立刻返回；如果被设为portMAX_DELAY，则会一直阻塞直到有数据可写
返回值	pdPASS：从队列读出数据入 errQUEUE_EMPTY：读取失败，因为队列空了。

11.2.6 查询

可以查询队列中有多少个数据、有多少空余空间。函数原型如下：

/*
 * 返回队列中可用数据的个数
 */
UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue );

/*
 * 返回队列中可用空间的个数
 */
UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue );

11.2.7 覆盖/偷看

当队列长度为1时，可以使用**xQueueOverwrite()或xQueueOverwriteFromISR()**来覆盖数据。

注意，队列长度必须为1。当队列满时，这些函数会覆盖里面的数据，这也以为着这些函数不会被阻塞。

函数原型如下：

/* 覆盖队列
 * xQueue: 写哪个队列
 * pvItemToQueue: 数据地址
 * 返回值: pdTRUE表示成功, pdFALSE表示失败
 */
BaseType_t xQueueOverwrite(
                           QueueHandle_t xQueue,
                           const void * pvItemToQueue
                      );

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

如果想让队列中的数据供多方读取，也就是说读取时不要移除数据，要留给后来人。那么可以使用"窥视"，也就是xQueuePeek()或xQueuePeekFromISR()。这些函数会从队列中复制出数据，但是不移除数据。这也意味着，如果队列中没有数据，那么"偷看"时会导致阻塞；一旦队列中有数据，以后每次"偷看"都会成功。

函数原型如下：

/* 偷看队列
 * xQueue: 偷看哪个队列
 * pvItemToQueue: 数据地址, 用来保存复制出来的数据
 * xTicksToWait: 没有数据的话阻塞一会
 * 返回值: pdTRUE表示成功, pdFALSE表示失败
 */
BaseType_t xQueuePeek(
                          QueueHandle_t xQueue,
                          void * const pvBuffer,
                          TickType_t xTicksToWait
                      );

BaseType_t xQueuePeekFromISR(
                                 QueueHandle_t xQueue,
                                 void *pvBuffer,
                             );

11.3 示例: 队列的基本使用

本节代码为：13_queue_game。以前使用环形缓冲区传输红外遥控器的数据，本程序改为使用队列。

11.4 示例: 使用队列实现多设备输入

本节代码为：14_queue_game_multi_input。

11.5 示例: 传输大块数据

本节代码为：FreeRTOS_10_queue_bigtransfer。

FreeRTOS的队列使用拷贝传输，也就是要传输uint32_t时，把4字节的数据拷贝进队列；要传输一个8字节的结构体时，把8字节的数据拷贝进队列。

如果要传输1000字节的结构体呢？写队列时拷贝1000字节，读队列时再拷贝1000字节？不建议这么做，影响效率！

这时候，我们要传输的是这个巨大结构体的地址：把它的地址写入队列，对方从队列得到这个地址，使用地址去访问那1000字节的数据。

使用地址来间接传输数据时，这些数据放在RAM里，对于这块RAM，要保证这几点：

RAM的所有者、操作者，必须清晰明了
这块内存，就被称为"共享内存"。要确保不能同时修改RAM。比如，在写队列之前只有由发送者修改这块RAM，在读队列之后只能由接收者访问这块RAM。
RAM要保持可用

这块RAM应该是全局变量，或者是动态分配的内存。对于动然分配的内存，要确保它不能提前释放：要等到接收者用完后再释放。另外，不能是局部变量。

FreeRTOS_10_queue_bigtransfer程序会创建一个队列，然后创建1个发送任务、1个接收任务：

创建的队列：长度为1，用来传输"char *"指针
发送任务优先级为1，在字符数组中写好数据后，把它的地址写入队列
接收任务优先级为2，读队列得到"char *"值，把它打印出来

这个程序故意设置接收任务的优先级更高，在它访问数组的过程中，接收任务无法执行、无法写这个数组。

main函数中创建了队列、创建了发送任务、接收任务，代码如下：

/* 定义一个字符数组 */
static char pcBuffer[100];

/* vSenderTask被用来创建2个任务，用于写队列
 * vReceiverTask被用来创建1个任务，用于读队列
 */
static void vSenderTask( void *pvParameters );
static void vReceiverTask( void *pvParameters );

/*-----------------------------------------------------------*/

/* 队列句柄, 创建队列时会设置这个变量 */
QueueHandle_t xQueue;

int main( void )
{
    
    
	prvSetupHardware();
	
    /* 创建队列: 长度为1，数据大小为4字节(存放一个char指针) */
    xQueue = xQueueCreate( 1, sizeof(char *) );

	if( xQueue != NULL )
	{
    
    
		/* 创建1个任务用于写队列
		 * 任务函数会连续执行，构造buffer数据，把buffer地址写入队列
		 * 优先级为1
		 */
		xTaskCreate( vSenderTask, "Sender", 1000, NULL, 1, NULL );

		/* 创建1个任务用于读队列
		 * 优先级为2, 高于上面的两个任务
		 * 这意味着读队列得到buffer地址后，本任务使用buffer时不会被打断
		 */
		xTaskCreate( vReceiverTask, "Receiver", 1000, NULL, 2, NULL );

		/* 启动调度器 */
		vTaskStartScheduler();
	}
	else
	{
    
    
		/* 无法创建队列 */
	}

	/* 如果程序运行到了这里就表示出错了, 一般是内存不足 */
	return 0;
}

发送任务的函数中，现在全局大数组pcBuffer中构造数据，然后把它的地址写入队列，代码如下：

static void vSenderTask( void *pvParameters )
{
    
    
	BaseType_t xStatus;
	static int cnt = 0;
	
	char *buffer;

	/* 无限循环 */
	for( ;; )
	{
    
    
		sprintf(pcBuffer, "www.100ask.net Msg %d\r\n", cnt++);
		buffer = pcBuffer; // buffer变量等于数组的地址, 下面要把这个地址写入队列
		
		/* 写队列
		 * xQueue: 写哪个队列
		 * pvParameters: 写什么数据? 传入数据的地址, 会从这个地址把数据复制进队列
		 * 0: 如果队列满的话, 即刻返回
		 */
		xStatus = xQueueSendToBack( xQueue, &buffer, 0 ); /* 只需要写入4字节, 无需写入整个buffer */

		if( xStatus != pdPASS )
		{
    
    
			printf( "Could not send to the queue.\r\n" );
		}
	}
}

接收任务的函数中，读取队列、得到buffer的地址、打印，代码如下：

static void vReceiverTask( void *pvParameters )
{
    
    
	/* 读取队列时, 用这个变量来存放数据 */
	char *buffer;
	const TickType_t xTicksToWait = pdMS_TO_TICKS( 100UL );	
	BaseType_t xStatus;

	/* 无限循环 */
	for( ;; )
	{
    
    
		/* 读队列
		 * xQueue: 读哪个队列
		 * &xReceivedStructure: 读到的数据复制到这个地址
		 * xTicksToWait: 没有数据就阻塞一会
		 */
		xStatus = xQueueReceive( xQueue, &buffer, xTicksToWait); /* 得到buffer地址，只是4字节 */

		if( xStatus == pdPASS )
		{
    
    
			/* 读到了数据 */
			printf("Get: %s", buffer);
		}
		else
		{
    
    
			/* 没读到数据 */
			printf( "Could not receive from the queue.\r\n" );
		}
	}
}

运行结果如下图所示：

11.6 示例: 邮箱(Mailbox)

本节代码为：FreeRTOS_11_queue_mailbox。

FreeRTOS的邮箱概念跟别的RTOS不一样，这里的邮箱称为"橱窗"也许更恰当：

它是一个队列，队列长度只有1
写邮箱：新数据覆盖旧数据，在任务中使用xQueueOverwrite()，在中断中使用xQueueOverwriteFromISR()。既然是覆盖，那么无论邮箱中是否有数据，这些函数总能成功写入数据。
读邮箱：读数据时，数据不会被移除；在任务中使用xQueuePeek()，在中断中使用xQueuePeekFromISR()。

这意味着，第一次调用时会因为无数据而阻塞，一旦曾经写入数据，以后读邮箱时总能成功。

main函数中创建了队列(队列长度为1)、创建了发送任务、接收任务：

发送任务的优先级为2，它先执行
接收任务的优先级为1

代码如下：

/* 队列句柄, 创建队列时会设置这个变量 */
QueueHandle_t xQueue;

int main( void )
{
    
    
	prvSetupHardware();
	
    /* 创建队列: 长度为1，数据大小为4字节(存放一个char指针) */
    xQueue = xQueueCreate( 1, sizeof(uint32_t) );

	if( xQueue != NULL )
	{
    
    
		/* 创建1个任务用于写队列
		 * 任务函数会连续执行，构造buffer数据，把buffer地址写入队列
		 * 优先级为2
		 */
		xTaskCreate( vSenderTask, "Sender", 1000, NULL, 2, NULL );

		/* 创建1个任务用于读队列
		 * 优先级为1
		 */
		xTaskCreate( vReceiverTask, "Receiver", 1000, NULL, 1, NULL );

		/* 启动调度器 */
		vTaskStartScheduler();
	}
	else
	{
    
    
		/* 无法创建队列 */
	}

	/* 如果程序运行到了这里就表示出错了, 一般是内存不足 */
	return 0;
}

发送任务、接收任务的代码和执行流程如下：

A：发送任务先执行，马上阻塞
BC：接收任务执行，这是邮箱无数据，打印"Could not …"。在发送任务阻塞过程中，接收任务多次执行、多次打印。
D：发送任务从阻塞状态退出，立刻执行、写队列
E：发送任务再次阻塞
FG、HI、……：接收任务不断"偷看"邮箱，得到同一个数据，打印出多个"Get: 0"
J：发送任务从阻塞状态退出，立刻执行、覆盖队列，写入1
K：发送任务再次阻塞
LM、……：接收任务不断"偷看"邮箱，得到同一个数据，打印出多个"Get: 1"

运行结果如下图所示：

11.7 队列集

假设有2个输入设备：红外遥控器、旋转编码器，它们的驱动程序应该专注于“产生硬件数据”，不应该跟“业务有任何联系”。比如：红外遥控器驱动程序里，它只应该把键值记录下来、写入某个队列，它不应该把键值转换为游戏的控制键。在红外遥控器的驱动程序里，不应该有游戏相关的代码，这样，切换使用场景时，这个驱动程序还可以继续使用。

把红外遥控器的按键转换为游戏的控制键，应该在游戏的任务里实现。

要支持多个输入设备时，我们需要实现一个“InputTask”，它读取各个设备的队列，得到数据后再分别转换为游戏的控制键。

InputTask如何及时读取到多个队列的数据？要使用队列集。

队列集的本质也是队列，只不过里面存放的是“队列句柄”。使用过程如下：

创建队列A，它的长度是n1
创建队列B，它的长度是n2
创建队列集S，它的长度是“n1+n2”
把队列A、B加入队列集S
这样
- 写队列A的时候，会顺便把队列A的句柄写入队列集S
- 写队列B的时候，会顺便把队列B的句柄写入队列集S
InputTask：
- 先读取队列集S，它的返回值是一个队列句柄，这样就可以知道哪个队列有有数据了
- 然后InputTask再读取这个队列句柄得到数据。

11.7.1 创建

函数原型如下：

QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength )

参数	说明
uxQueueLength	队列集长度，最多能存放多少个数据(队列句柄)
返回值	非0：成功，返回句柄，以后使用句柄来操作队列 NULL：失败，因为内存不足

11.7.2 把队列加入队列集

函数原型如下：

BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore,
                               QueueSetHandle_t xQueueSet );

参数	说明
xQueueOrSemaphore	队列句柄，这个队列要加入队列集
xQueueSet	队列集句柄
返回值	pdTRUE：成功 pdFALSE：失败

11.7.3读取队列集

函数原型如下：

QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet,
                                                TickType_t const xTicksToWait );

参数	说明
xQueueSet	队列集句柄
xTicksToWait	如果队列集空则无法读出数据，可以让任务进入阻塞状态，xTicksToWait表示阻塞的最大时间(Tick Count)。如果被设为0，无法读出数据时函数会立刻返回；如果被设为portMAX_DELAY，则会一直阻塞直到有数据可写
返回值	NULL：失败，队列句柄：成功

本章完

第11章_freeRTOS入门与工程实践之队列(queue)

第11章队列(queue)

11.1 队列的特性

1.1.1 常规操作

11.1.2 传输数据的两种方法

11.1.3 队列的阻塞访问

11.2 队列函数

11.2.1 创建

11.2.2 复位

11.2.3 删除

11.2.4 写队列

11.2.5 读队列

11.2.6 查询

11.2.7 覆盖/偷看

11.3 示例: 队列的基本使用

11.4 示例: 使用队列实现多设备输入

11.5 示例: 传输大块数据

11.6 示例: 邮箱(Mailbox)

11.7 队列集

11.7.1 创建

11.7.2 把队列加入队列集

11.7.3读取队列集

猜你喜欢

第11章_freeRTOS入门与工程实践之队列(queue)

第11章 队列(queue)

11.1 队列的特性

1.1.1 常规操作

11.1.2 传输数据的两种方法

11.1.3 队列的阻塞访问

11.2 队列函数

11.2.1 创建

11.2.2 复位

11.2.3 删除

11.2.4 写队列

11.2.5 读队列

11.2.6 查询

11.2.7 覆盖/偷看

11.3 示例: 队列的基本使用

11.4 示例: 使用队列实现多设备输入

11.5 示例: 传输大块数据

11.6 示例: 邮箱(Mailbox)

11.7 队列集

11.7.1 创建

11.7.2 把队列加入队列集

11.7.3读取队列集

猜你喜欢

第11章队列(queue)