参考和感谢zhzht19861011：FreeRTOS队列分析
队列是主要的任务间通讯方式，可以在任务与任务间、中断和任务间传送信息。
大多数情况下，队列用于具有线程保护的FIFO（先进先出）缓冲区。
发送到队列的消息是通过拷贝实现的，这意味着队列存储的数据是原数据，而不是原数据的引用。
API函数允许指定阻塞时间。
- 每当任务企图从一个空的队列读取数据时，任务会进入阻塞状态（这样任务不会消耗任何CPU时间并且另一个任务可以运行）直到队列中出现有效数据或者阻塞时间到期。
- 当任务企图向一个满的队列写数据时，任务会进入阻塞状态，直到队列中出现有效空间或者阻塞时间到期。
队列的基本用法：
- 定义一个队列句柄变量，用于保存创建的队列：xQueueHandle xQueue1;
- 使用API函数xQueueCreate()创建一个队列。
- 如果希望使用先进先出队列，使用API函数xQueueSend()或xQueueSendToBack()向队列投递队列项。
如果希望使用后进先出队列，使用API函数xQueueSendToFront()向队列投递队列项。
如果在中断服务程序中，切记使用它们的带中断保护版本。 - 使用API函数xQueueReceive()从队列读取队列项，如果在中断服务程序中，切记使用它们的带中断保护版本。
typedef struct QueueDefinition
{
int8_t *pcHead; /* 指向队列存储区起始位置,即第一个队列项 */
int8_t *pcTail; /* 指向队列存储区结束后的下一个字节 */
int8_t *pcWriteTo; /* 指向下队列存储区的下一个空闲位置 */
union /* 使用联合体用来确保两个互斥的结构体成员不会同时出现 */
{
int8_t *pcReadFrom; /* 当结构体用于队列时,这个字段指向出队项目中的最后一个. */
UBaseType_t uxRecursiveCallCount;/* 当结构体用于互斥量时,用作计数器,保存递归互斥量被"获取"的次数. */
} u;
List_t xTasksWaitingToSend; /* 因为等待入队而阻塞的任务列表,按照优先级顺序存储 */
List_t xTasksWaitingToReceive; /* 因为等待队列项而阻塞的任务列表,按照优先级顺序存储 */
volatile UBaseType_t uxMessagesWaiting;/*< 当前队列的队列项数目 */
UBaseType_t uxLength; /* 队列项的数目 */
UBaseType_t uxItemSize; /* 每个队列项的大小 */
volatile BaseType_t xRxLock; /* 队列上锁后,存储从队列收到的列表项数目，如果队列没有上锁，设置为queueUNLOCKED */
volatile BaseType_t xTxLock; /* 队列上锁后,存储发送到队列的列表项数目，如果队列没有上锁，设置为queueUNLOCKED */
#if ( configUSE_QUEUE_SETS == 1 )
struct QueueDefinition *pxQueueSetContainer;
#endif
#if ( configUSE_TRACE_FACILITY == 1 )
UBaseType_t uxQueueNumber;
uint8_t ucQueueType;
#endif
#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
uint8_t ucStaticAllocationFlags;
#endif
} xQUEUE;
typedef xQUEUE Queue_t;
1. 队列创建函数
创建队列API函数xQueueCreate()，但其实这是一个宏，只是定义的像函数而已。真正被执行的函数是xQueueGenericCreate()，我们称这个函数为通用队列创建函数。
QueueHandle_t xQueueGenericCreate
(
const UBaseType_t uxQueueLength, //队列项数目
const UBaseType_t uxItemSize, //每个队列项的大小
uint8_t *pucQueueStorage, //指向定义队列存储空间
StaticQueue_t *pxStaticQueue, //指向队列控制结构体
const uint8_t ucQueueType
)
{
Queue_t *pxNewQueue;
/* 如果使能可视化跟踪调试,这里用来消除编译器警告. */
( void ) ucQueueType;
/*分配队列结构体和队列项存储空间.可以静态也可以动态分配,取决于参数值,FreeRTOS默认采取动态分配 */
pxNewQueue = prvAllocateQueueMemory( uxQueueLength, uxItemSize, &pucQueueStorage, pxStaticQueue );
// 成功分配队列存储空间
if( pxNewQueue != NULL )
{
if( uxItemSize == ( UBaseType_t ) 0 )
{
/* 没有为队列项存储分配内存,但是pcHead指针不能设置为NULL,因为队列用作互斥量时,
pcHead要设置成NULL.这里只是将pcHead指向一个已知的区域 */
pxNewQueue->pcHead = ( int8_t * ) pxNewQueue;
}
else
{
/* 指向队列项存储区域*/
pxNewQueue->pcHead = ( int8_t * ) pucQueueStorage;
}
/* 初始化队列结构体成员*/
pxNewQueue->uxLength = uxQueueLength;
pxNewQueue->uxItemSize = uxItemSize;
( void ) xQueueGenericReset( pxNewQueue, pdTRUE );
#if ( configUSE_TRACE_FACILITY == 1 )
{
pxNewQueue->ucQueueType = ucQueueType;
}
#endif /* configUSE_TRACE_FACILITY */
traceQUEUE_CREATE( pxNewQueue );
}
return ( QueueHandle_t ) pxNewQueue;
}
- uxQueueLength：队列项数目
- uxItemSize：每个队列项的大小
- pucQueueStorage：使用静态分配队列时才使用，指向定义队列存储空间，如果使用动态分配队列空间（默认），向这个参数传递NULL。
- pxStaticQueue：使用静态分配队列时才使用，指向队列控制结构体，如果使用动态分配队列空间（默认），向这个参数传递NULL。
- ucQueueType：类型。可能的值为：
queueQUEUE_TYPE_BASE：表示队列
queueQUEUE_TYPE_SET：表示队列集合
queueQUEUE_TYPE_MUTEX：表示互斥量
queueQUEUE_TYPE_COUNTING_SEMAPHORE：表示计数信号量
queueQUEUE_TYPE_BINARY_SEMAPHORE：表示二进制信号量
queueQUEUE_TYPE_RECURSIVE_MUTEX ：表示递归互斥量
参数ucQueueType只是用来可视化跟踪调试用。
首先调用函数prvAllocateQueueMemory分配队列结构体和队列项存储空间，结构体和队列项在存储空间上是连续的。
分配成功后初始化成员，然后调用函数xQueueGenericReset()初始化剩下的结构体成员。
假设我们申请了3个队列项，每个队列项占用4字节存储空间（即uxLength=3、uxItemSize=4），则经过初始化后的队列内存如图所示。
2. 入队
队列项入队也称为投递（Send），分为带中断保护的入队操作和不带中断保护的入队操作。每种情况下又分为从队列尾部入队和从队列首部入队两种操作，从队列尾部入队还有一种特殊情况，覆盖式入队，即队列满后自动覆盖最旧的队列项。
2.1 xQueueGenericSend()
这个函数用于入队操作，绝不可以用在中断服务程序中。
BaseType_t xQueueGenericSend
(
QueueHandle_t xQueue, //队列句柄
const void * const pvItemToQueue, //指针，指向要入队的项目
TickType_t xTicksToWait, //如果队列满，等待队列空闲的最大时间,时间单位为系统节拍时钟周期
const BaseType_t xCopyPosition //入队位置，可以选择从队列尾入队、从队列首入队和覆盖式入队。
)
{
BaseType_t xEntryTimeSet = pdFALSE, xYieldRequired;
TimeOut_t xTimeOut;
Queue_t * const pxQueue = ( Queue_t * ) xQueue;
for( ;; )
{
taskENTER_CRITICAL();
{
/* 队列还有空闲?正在运行的任务一定要比等待访问队列的任务优先级高.如果使用覆盖式入队,则不需要关注队列是否满*/
if( ( pxQueue->uxMessagesWaiting < pxQueue->uxLength ) || ( xCopyPosition == queueOVERWRITE ) )
{
/*完成数据拷贝工作,分为从队列尾入队,从队列首入队和覆盖式入队*/
xYieldRequired = prvCopyDataToQueue( pxQueue, pvItemToQueue, xCopyPosition );
/* 如果有任务在此等待队列数据到来,则将该任务解除阻塞*/
if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
{
/*有任务因等待出队而阻塞,则将任务从队列等待接收列表中删除,然后加入到就绪列表*/
if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
{
/* 解除阻塞的任务有更高的优先级,则当前任务要让出CPU,因此触发一个上下文切换.又因为现在还在临界区,要等退出临界区后,才会执行上下文切换.*/
queueYIELD_IF_USING_PREEMPTION();
}
}
else if( xYieldRequired != pdFALSE )
{
/* 这个分支处理特殊情况*/
queueYIELD_IF_USING_PREEMPTION();
}
taskEXIT_CRITICAL();
return pdPASS;
}
else
{
if( xTicksToWait == ( TickType_t ) 0 )
{
/* 如果队列满并且没有设置超时,则直接退出 */
taskEXIT_CRITICAL();
/* 返回队列满错误码 */
return errQUEUE_FULL;
}
else if( xEntryTimeSet == pdFALSE )
{
/* 队列满并且规定了阻塞时间,因此需要配置超时结构体对象 */
vTaskSetTimeOutState( &xTimeOut );
xEntryTimeSet = pdTRUE;
}
}
}
taskEXIT_CRITICAL();
/* 退出临界区,至此,中断和其它任务可以向这个队列执行入队(投递)或出队(读取)操作.因为队列满,任务无法入队,下面的代码将当前任务将阻塞在这个队列上,在这段代码执行过程中我们需要挂起调度器,防止其它任务操作队列事件列表;挂起调度器虽然可以禁止其它任务操作这个队列,但并不能阻止中断服务程序操作这个队列,因此还需要将队列上锁,防止中断程序读取队列后,使阻塞在出队操作其它任务解除阻塞,执行上下文切换(因为调度器挂起后,不允许执行上下文切换) */
vTaskSuspendAll();
prvLockQueue( pxQueue );
/* 查看任务的超时时间是否到期 */
if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )
{
if( prvIsQueueFull( pxQueue ) != pdFALSE )
{
/*超时时间未到期,并且队列仍然满*/
vTaskPlaceOnEventList( &( pxQueue->xTasksWaitingToSend ), xTicksToWait );
/* 解除队列锁,如果有任务要解除阻塞,则将任务移到挂起就绪列表中(因为当前调度器挂起,所以不能移到就绪列表)*/
prvUnlockQueue( pxQueue );
/* 恢复调度器,将任务从挂起就绪列表移到就绪列表中*/
if( xTaskResumeAll() == pdFALSE )
{
portYIELD_WITHIN_API();
}
}
else
{
/* 队列有空闲,重试 */
prvUnlockQueue( pxQueue );
( void ) xTaskResumeAll();
}
}
else
{
/* 超时时间到期,返回队列满错误码*/
prvUnlockQueue( pxQueue );
( void ) xTaskResumeAll();
traceQUEUE_SEND_FAILED( pxQueue );
return errQUEUE_FULL;
}
}
}
通用入队流程
调用函数prvCopyDataToQueue()将要入队的数据拷贝到队列。这个函数处理三种入队情况，第一种是队列项大小为0时（即队列结构体成员uxItemSize为0，比如二进制信号量和计数信号量），不进行数据拷贝工作，而是将队列项计数器加1（即队列结构体成员uxMessagesWaiting++）；第二种情况是从队列尾入队时，则将数据拷贝到指针pxQueue->pcWriteTo指向的地方、更新指针指向的位置、队列项计数器加1；第三种情况是从队列首入队时，则将数据拷贝到指针pxQueue->u.pcReadFrom指向的地方、更新指针指向的位置、队列项计数器加1。如果是覆盖式入队，还会调整队列项计数器的值。
队列结构体中有两个成员跟队列上锁有关：xRxLock和xTxLock。这两个成员变量为queueUNLOCKED（宏，定义为-1）时，表示队列未上锁；当这两个成员变量为queueLOCKED_UNMODIFIED（宏，定义为0）时，表示队列上锁。
2.2 xQueueGenericSendFromISR ()
BaseType_t xQueueGenericSendFromISR
(
QueueHandle_t xQueue,
const void * const pvItemToQueue,
BaseType_t * const pxHigherPriorityTaskWoken,
如果入队导致一个任务解锁，并且解锁的任务优先级高于当前运行的任务，
则该函数将*pxHigherPriorityTaskWoken设置成pdTRUE。
如果xQueueSendFromISR()设置这个值为pdTRUE，则中断退出前需要一次上下文切换。
const BaseType_t xCopyPosition
)
{
BaseType_t xReturn;
UBaseType_t uxSavedInterruptStatus;
Queue_t * const pxQueue = ( Queue_t * ) xQueue;
uxSavedInterruptStatus = portSET_INTERRUPT_MASK_FROM_ISR();
{
if( ( pxQueue->uxMessagesWaiting < pxQueue->uxLength ) || ( xCopyPosition == queueOVERWRITE ) )
{
traceQUEUE_SEND_FROM_ISR( pxQueue );
/*完成数据拷贝工作,分为从队列尾入队,从队列首入队和覆盖式入队*/
( void ) prvCopyDataToQueue( pxQueue, pvItemToQueue, xCopyPosition );
/*检查队列是否上锁,如果上锁,则队列事件列表不能被改变 */
if( pxQueue->xTxLock == queueUNLOCKED )
{ /*队列没有上锁*/
if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
{
if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
{
/* 解除阻塞的任务优先级比当前任务高,记录上下文切换请求,等返回中断服务程序后,可以显示的强制上下文切换 */
if( pxHigherPriorityTaskWoken != NULL )
{
*pxHigherPriorityTaskWoken = pdTRUE;
}
}
}
}
else
{
/* 队列上锁,增加锁计数器,等到任务解除队列锁时,使用这个计数器就可以知道有多少数据入队,可以最多解除多少个因等待从队列读数据而阻塞的任务 */
++( pxQueue->xTxLock );
}
xReturn = pdPASS;
}
else
{
xReturn = errQUEUE_FULL;
}
}
portCLEAR_INTERRUPT_MASK_FROM_ISR( uxSavedInterruptStatus );
return xReturn;
}
3 出队
