4.3 FreeRTOS----队列的应用

xQueueCreate（）API函数

        在使用队列之前必须明确创建一个队列。

        队列由句柄引用，它们是QueueHandle_t类型的变量。 xQueueCreate() API函数创建一个队列，并返回一个引用其创建的队列的QueueHandle_t。

        FreeRTOS V9.0.0还包括xQueueCreateStatic（）函数，它在编译时分配静态创建队列所需的内存：FreeRTOS在创建队列时从FreeRTOS堆分配RAM。 RAM用于保存队列数据结构和队列中包含的项目。 如果没有足够的堆RAM可用于要创建的队列，xQueueCreate（）将返回NULL。

函数原型及参数说明如下：

QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength, UBaseType_t uxItemSize );

参数描述

uxQueueLength 

创建队列的最大长度

uxItemSize 

可以存储在队列中的每个数据项的大小（以字节为单位）。返回值如果返回NULL，则不能创建队列，因为FreeRTOS可用的堆内存不足以分配队列数据结构和存储区域。
返回的非NULL值表示已成功创建队列。 返回值应存储为创建队列的句柄。

        创建队列后，可以使用xQueueReset（）API函数将队列返回到原始的空状态。

xQueueSendToBack（）和xQueueSendToFront（）API函数

        可以预期，xQueueSendToBack（）用于将数据发送到队列的后端（尾部），xQueueSendToFront（）用于将数据发送到队列的前端（head）。

        xQueueSend（）等同于和xQueueSendToBack（）完全相同的。

       注意：不要从中断服务程序调用xQueueSendToFront（）或xQueueSendToBack（）。 中断安全版本中应该使用xQueueSendToFrontFromISR（）和xQueueSendToBackFromISR（）API函数。

函数原型及参数说明如下：

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

参数描述

xQueue 

要发送（写入）数据的队列的句柄。 队列句柄将从调用xQueueCreate（）返回，用于创建队列。

pvItemToQueue 

指向要复制到队列中的数据的指针。
队列可以保存的每个项目的大小在创建队列时设置，因此这么多字节将从pvItemToQueue复制到队列存储区域。

xTicksToWait 

如果队列已经满了，则任务应保持在“已阻止”状态的最大时间等待队列上的空间。
xQueueSendToFront（）和xQueueSendToBack（）将立即返回，如果xTicksToWait为零并且队列已满。
阻塞时间在系统时间周期中指定，因此其表示的绝对时间取决于系统时间频率。 宏pdMS_TO_TICKS（）可用于将以毫秒指定的时间转换为在ticks中指定的时间。
将xTicksToWait设置为portMAX_DELAY将导致任务无限期地等待（没有超时），如果在FreeRTOSConfig.h中将INCLUDE_vTaskSuspend设置为1。返回值有两种可能的返回值：
1. pdPASS
只有当数据成功发送到队列时，才会返回pdPASS。
如果指定了一个阻塞时间（xTicksToWait不为零），则调用任务可能被置于阻塞状态，等待空间在队列中可用，然后返回该函数，但数据已成功写入 在阻塞时间过期前排队。
2. errQUEUE_FULL
由于队列已满，因此无法将数据写入队列时将返回errQUEUE_FULL。
如果指定了一个阻塞时间（xTicksToWait不为零），则调用任务将被置于阻塞状态，等待另一个任务或中断在队列中空格，但指定的阻塞时间在发生之前已过期。

xQueueReceive（）API函数

        xQueueReceive（）用于从队列中接收（读取）一个项目。 接收到的项目将从队列中删除。
        注意：不要从中断服务程序调用xQueueReceive（）。 中断中应该使用xQueueReceiveFromISR（）API函数。

        函数原型及参数说明如下：

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

参数描述

xQueue 

从中接收数据的队列的句柄（读）。 队列句柄将从调用用于创建队列的函数xQueueCreate（）返回。

pvBuffer 

指向接收到的数据将被复制到的存储器的指针。

创建队列时设置队列所保存的每个数据项的大小。 pvBuffer指向的内存必须至少足够大以容纳多个字节。

xTicksToWait 

如果队列已经为空，则任务应保持在“阻塞”状态的最大时间量，以等待数据在队列上可用。
如果xTicksToWait为零，那么如果队列已经为空，则xQueueReceive（）将立即返回。
阻塞时间在刻度周期中指定，因此其表示的绝对时间取决于刻度频率。 宏pdMS_TO_TICKS（）可用于将以毫秒指定的时间转换为在ticks中指定的时间。
将xTicksToWait设置为portMAX_DELAY将导致任务无限期地等待（没有超时），因为FreeRTOSConfig.h中的INCLUDE_vTaskSuspend设置为1。返回值有两种可能的返回值：
1. pdPASS
只有在从队列中成功读取数据时，才会返回pdPASS。
如果指定了一个阻塞时间（xTicksToWait不为零），则调用任务可能被置于阻塞状态，等待数据在队列上可用，但在块时间之前成功从队列中读取数据过期。
2. errQUEUE_EMPTY
由于队列已经为空，因此无法从队列读取数据时将返回errQUEUE_EMPTY。
如果指定了一个阻塞时间（xTicksToWait不为零），则调用任务将被置于阻塞状态，以等待另一个任务或中断将数据发送到队列，但在发生之前已过期。

uxQueueMessagesWaiting（）API函数

        uxQueueMessagesWaiting（）用于查询当前在队列中的项目数。
        注意：不要从中断服务程序调用uxQueueMessagesWaiting（）。 应该使用中断安全的uxQueueMessagesWaitingFromISR（）。

        函数原型及参数说明如下：

UBaseType_t uxQueueMessagesWaiting( QueueHandle_t xQueue );

参数描述

xQueue 

查询队列的句柄。 队列句柄将从用于创建队列的xQueueCreate（）API函数返回。返回值正在查询的队列当前持有的项目数。 如果返回0，则队列为空。