FreeRTOS进阶之队列示例完全解析

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;

QueueHandle_t xQueueGenericCreate
        ( 
                const UBaseType_t uxQueueLength, 
                const UBaseType_t uxItemSize, 
                uint8_t *pucQueueStorage, 
                StaticQueue_t *pxStaticQueue, 
                const uint8_t ucQueueType 
        )

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;
}

BaseType_t xQueueGenericSend
				( 
					QueueHandle_t xQueue, 
					const void * const pvItemToQueue, 
					TickType_t xTicksToWait, 
					const BaseType_t xCopyPosition 
				)

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;
        }
    }
}

BaseType_t xQueueGenericSendFromISR
				( 
						QueueHandle_t xQueue, 
						const void * const pvItemToQueue, 
						BaseType_t * const pxHigherPriorityTaskWoken, 
						const BaseType_t xCopyPosition 
				)

BaseType_t xQueueGenericSendFromISR(
 				QueueHandle_t xQueue, 
				const void * const pvItemToQueue, 
				BaseType_t * const pxHigherPriorityTaskWoken, 
				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;
}