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,则队列为空。 |