Freertos学习：07-队列

--- title: rtos-freertos-07-队列 EntryName : rtos-freertos-07 date: 2020-06-23 09:43:28 categories: tags: - ipc - queue - freertos ---

章节概述：

介绍 FreeRTOS中的任务间通讯机制：队列的使用（尽管FreeRTOS中没有进程的概念，但为了统一，我们还是以进程间通讯(IPC)的说法）

介绍

队列是主要的任务间通讯方式。可以在任务与任务间、中断和任务间传送信息。

大多数情况下，队列用于具有线程保护的FIFO（先进先出）缓冲区。

特性

FreeRTOS队列具有以下特性：

• 通过拷贝传递数据

当信息的大小到达一个临界点后，逐字节拷贝整个信息是不实际的，可以定义一个指针队列，只拷贝指向消息的指针来代替整个信息拷贝。

FreeRTOS+UDP IP栈例程正是使用这种方法向FreeRTOS协议栈传递大量网络数据的。

但我们还可以通过定义结构体，并在其中使用指针：

• 通过定义保存一个结构体变量的队列实现：变长消息（一个成员保存缓存数据的大小；另一个成员指向要入队的缓存）

• 通过定义保存一个结构体变量的队列实现：单个队列可以接收不同类型信息，并且信息可以来自不同的位置。（一个成员保存信息类型；另一个成员保存信息数据或者指向信息数据的指针）。数据如何解读取决于信息类型。

管理FreeRTOS+UDP IP栈的任务正是使用单个队列接收ARP定时器时间通知、以太网硬件传送来的数据包、从应用层传送来的数据包、网络关闭事件等等。

• 队列内存区域分配由内核完成，我们不需要关心数据如何出入队。
• 天生适用于那些内存保护（MPU）场合。一个具有内存区域保护的任务可以向另一个具有内存区域保护的任务传递数据，因为调用队列发送函数会引起RTOS提升微控制器特权级别。只有RTOS（具有所有特权）才可以访问队列存储区域。
• 在中断函数中使用独立的API。将RTOS任务API和中断服务例程API分来实现意味着可以避免执行时的上下文调用检查开销，还意味着在大多数情况下，与其它RTOS产品相比，用户创建中断服务例程会更简单。

基本用法

队列的基本用法：

• 定义一个队列句柄变量，用于保存创建的队列：xQueueHandle xQueue1;
• 使用API函数xQueueCreate()创建一个队列。
• 如果希望使用先进先出队列，使用API函数xQueueSend()向队列投递队列项。如果希望使用后进先出队列，使用API函数xQueueSendToFront()向队列投递队列项。
• 使用API函数xQueueReceive()从队列读取队列项。

如果在中断服务程序中，切记使用它们的带中断保护版本。

基本操作

创建队列

QueueHandle_t xQueueCreate (UBaseType_t uxQueueLength, UBaseType_t uxItemSize);

描述：创建新队列。为新队列分配指定的存储空间并返回队列句柄。

参数解析：

• usQueueLength：队列项数目

• uxItemSize：每个队列项大小，单位是字节。队列项通过拷贝入队而不是通过引用入队，因此需要队列项的大小。每个队列项的大小必须相同。

返回值：成功创建队列返回队列句柄，否则返回0。

例子：

struct AMessage
{
    portCHAR ucMessageID;
    portCHAR ucData[ 20 ];
};
void vATask( void*pvParameters )
{
    xQueueHandle xQueue1, xQueue2;
    // 创建一个队列，队列能包含10个unsigned long类型的值。
    xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ));
    if( xQueue1 ==0 )
    {
        // 队列创建失败，不可以使用
    }
    // 创建一个队列，队列能包含10个 Amessage结构体指针类型的值。
    // 这样可以通过传递指针变量来包含大量数据。
    xQueue2 =xQueueCreate( 10, sizeof( struct AMessage * ) );
    if( xQueue2 ==0 )
    {
        // 队列创建失败，不可以使用
    }
    // ... 任务的其它代码.
}

注意：创建完成句柄以后，此后对队列的操作函数都需要使用QueueHandle_t xQueue，篇幅有限，会对此参数进行省略。

删除队列

void vQueueDelete( QueueHandle_t xQueue );

描述：删除队列并释放所有分配给队列的内存。

复位队列

BaseType_t xQueueReset( QueueHandle_t xQueue );

描述：将队列复位到初始状态。

获取信息

获取队列入队信息数目

UBaseType_t uxQueueMessagesWaiting( QueueHandle_t xQueue );

// 具有中断保护的版本:
UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue )。

描述：获取队列中存储的信息数目。

获取队列的空闲数目

UBaseType_t uxQueueSpacesAvailable( QueueHandle_t xQueue );

描述：获取队列的空闲数目。

查询队列是否为空

BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue );

描述：查询队列是否为空。这个函数仅用于ISR。

返回值：队列非空返回pdFALSE，其它值表示队列为空。

查询队列是否满

描述：查询队列是否满，仅用于ISR。

BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue )

返回值：没有满返回pdFALSE；其它值表示队列满。

数据传输

向队列投递一个值

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

// 中断保护的版本
BaseType_t xQueueSendFromISR(
    QueueHandle_t xQueue,
    const void *pvItemToQueue,
    BaseType_t *pxHigherPriorityTaskWoken);

描述：向队列尾部投递一个队列项。

参数解析：

• pvItemToQueue：指针，指向要入队的项目。要保存到队列中的项目字节数在队列创建时就已确定。因此要从指针pvItemToQueue指向的区域拷贝到队列存储区域的字节数，也已确定。
• xTicksToWait：如果队列满，任务等待队列空闲的最大时间。如果队列满并且xTicksToWait被设置成0，函数立刻返回。时间单位为系统节拍时钟周期，因此宏portTICK_PERIOD_MS可以用来辅助计算真实延时值。如果INCLUDE_vTaskSuspend设置成1，并且指定延时为portMAX_DELAY将引起任务无限阻塞（没有超时）。
• pxHigherPriorityTaskWoken：如果入队导致一个任务解锁，并且解锁的任务优先级高于当前运行的任务，则该函数将*pxHigherPriorityTaskWoken设置成pdTRUE。如果xQueueSendFromISR()设置这个值为pdTRUE，则中断退出前需要一次上下文切换。从FreeRTOS V7.3.0起， pxHigherPriorityTaskWoken 作为可选参数，并可以设置为NULL。

返回值：队列项入队成功返回pdTRUE，否则返回errQUEUE_FULL。

例子：

struct AMessage
{
    portCHAR ucMessageID;
    portCHAR ucData[ 20 ];
}xMessage;
unsigned portLONG ulVar = 10UL;
void vATask( void *pvParameters )
{
    xQueueHandle xQueue1, xQueue2;
    struct AMessage *pxMessage;
    /*创建一个队列，队列能包含10个unsigned long类型的值。*/
    xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );
    /* 创建一个队列，队列能包含10个 Amessage结构体指针类型的值。
       这样可以通过传递指针变量来包含大量数据。*/
    xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
    // ...
    if( xQueue1 != 0 )
    {
        /*1个unsigned long型数据入队.如果需要等待队列空间变的有效，
         会最多等待10个系统节拍周期*/
        if( xQueueSend( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) !=pdPASS )
        {
            /*消息入队失败*/
        }
    }
    if( xQueue2 != 0 )
    {
        /* 发送一个指向结构体Amessage的对象，如果队列满也不等待 */
        pxMessage = & xMessage;
        xQueueSend( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 );
    }
    //... 任务其余代码.
}

// xQueueSendFromISR 例子
void vBufferISR( void )
{
    portCHARcIn;
    portBASE_TYPE xHigherPriorityTaskWoken;
 
    /* 初始化，没有唤醒任务*/
    xHigherPriorityTaskWoken = pdFALSE;
 
    /* 直到缓冲区为空 */
    do
    {
        /* 从缓冲区获得一个字节数据 */
        cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                                      
 
        /* 投递这个数据 */
        xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
    }while( portINPUT_BYTE( BUFFER_COUNT ) );
 
    /* 这里缓冲区已空，如果需要进行一个上下文切换*/
    /*根据不同移植平台，这个函数也不同*/
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

向队尾投递一个值

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

// 中断保护的版本
BaseType_t xQueueSendToBackFromISR (QueueHandle_t xQueue,
            const void *pvItemToQueue, BaseType_t *pxHigherPriorityTaskWoken );

描述：向队列尾投递一个队列项。

参数解析：同xQueueSend或 xQueueSendFromISR。

返回值：同xQueueSend。

向队首投递一个值

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

// 有中断保护
BaseType_t xQueueSendToFrontFromISR (QueueHandle_t xQueue,
                                     const void *pvItemToQueue,
                                     BaseType_t *pxHigherPriorityTaskWoken);

描述：向队列首部投递一个队列项。

参数解析：

• pvItemToQueue：指针，指向要入队的项目。要保存到队列中的项目字节数在队列创建时就已确定。因此要从指针pvItemToQueue指向的区域拷贝到队列存储区域的字节数，也已确定。
• xTicksToWait：如果队列满，任务等待队列空闲的最大时间。如果队列满并且xTicksToWait被设置成0，函数立刻返回。时间单位为系统节拍时钟周期，因此宏portTICK_PERIOD_MS可以用来辅助计算真实延时值。如果INCLUDE_vTaskSuspend设置成1，并且指定延时为portMAX_DELAY将引起任务无限阻塞（没有超时）。
• pxHigherPriorityTaskWoken：如果入队导致一个任务解锁，并且解锁的任务优先级高于当前运行的任务，则该函数将*pxHigherPriorityTaskWoken设置成pdTRUE。如果xQueueSendFromISR()设置这个值为pdTRUE，则中断退出前需要一次上下文切换。从FreeRTOS V7.3.0起，pxHigherPriorityTaskWoken称为一个可选参数，并可以设置为NULL。

返回值：队列项入队成功返回pdTRUE，否则返回errQUEUE_FULL。

从队列中读取一个值

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

// 带有中断保护的版本
BaseType_t xQueueReceiveFromISR (QueueHandle_t xQueue,
                                 void *pvBuffer, 
                                 BaseType_t *pxHigherPriorityTaskWoken);

描述：从队列中读取一个队列项并把该队列项从队列中删除。

参数解析：

• pvBuffer：指向一个缓冲区，用于拷贝接收到的列表项。必须提供足够大的缓冲区以便容纳队列项。
• xTicksToWait：要接收的项目队列为空时，允许任务最大阻塞时间。如果设置该参数为0，则表示即队列为空也立即返回。阻塞时间的单位是系统节拍周期，宏portTICK_RATE_MS可辅助计算真实阻塞时间。如果INCLUDE_vTaskSuspend设置成1，并且阻塞时间设置成portMAX_DELAY，将会引起任务无限阻塞（不会有超时）。
• pxHigherPriorityTaskWoken：如果入队导致一个任务解锁，并且解锁的任务优先级高于当前运行的任务，则该函数将*pxHigherPriorityTaskWoken设置成pdTRUE。如果xQueueSendFromISR()设置这个值为pdTRUE，则中断退出前需要一次上下文切换。从FreeRTOS V7.3.0起，pxHigherPriorityTaskWoken称为一个可选参数，并可以设置为NULL。

返回值：成功接收到列表项返回pdTRUE，否则返回pdFALSE。

例子：

struct AMessage
{
    portCHAR ucMessageID;
    portCHAR ucData[ 20 ];
} xMessage;
 
xQueueHandle xQueue;
 
// 创建一个队列并投递一个值
void vATask( void *pvParameters )
{
     struct AMessage *pxMessage;
 
     // 创建一个队列，队列能包含10个 Amessage结构体指针类型的值。
     // 这样可以通过传递指针变量来包含大量数据。
     xQueue =xQueueCreate( 10, sizeof( struct AMessage * ) );
     if( xQueue == 0)
     {
          // 创建队列失败
    }
    // ...
    // 向队列发送一个指向结构体对象Amessage的指针，如果队列满不等待
    pxMessage = & xMessage;
    xQueueSend(xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );
    // ... 其它代码
}
 
// 该任务从队列中接收一个队列项
voidvADifferentTask( void *pvParameters )
{
    struct AMessage *pxRxedMessage;
 
    if( xQueue != 0)
    {
        // 从创建的队列中接收一个消息，如果消息无效，最多阻塞10个系统节拍周期
        if(xQueueReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )
        {
            // 现在pcRxedMessage 指向由vATask任务投递进来的结构体Amessage变量
        }
    }
   // ... 其它代码
 }

// xQueueReceiveFromISR 例程

/* 该函数创建一个队列并投递一些值 */
voidvAFunction( void *pvParameters )
{
     portCHAR cValueToPost;
     const portTickType xBlockTime = (portTickType )0xff;
 
     /*创建一个队列，可以容纳10个portCHAR型变量 */
     xQueue = xQueueCreate( 10, sizeof( portCHAR ) );
     if( xQueue == 0 )
     {
          /* 队列创建失败 */
     }
    /*…... */
    /* 投递一些字符，在ISR中使用。如果队列满，任务将会阻塞xBlockTime 个系统节拍周期 */
    cValueToPost = 'a';
    xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
    cValueToPost = 'b';
    xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
    /*... 继续投递字符 ... 当队列满时，这个任务会阻塞*/
    cValueToPost = 'c';
    xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
}
 
/* ISR：输出从队列接收到的所有字符 */
voidvISR_Routine( void )
{
     portBASE_TYPE xTaskWokenByReceive = pdFALSE;
     portCHAR cRxedChar;
 
     while( xQueueReceiveFromISR( xQueue, ( void *) &cRxedChar, &xTaskWokenByReceive) )
    {
       /* 接收到一个字符串，输出.*/
       vOutputCharacter( cRxedChar );
       /* 如果从队列移除一个字符串后唤醒了向此队列投递字符的任务，那么参数xTaskWokenByReceive将会设置成pdTRUE，这个循环无论重复多少次，仅会
          有一个任务被唤醒。*/
    }
    /*这里缓冲区已空，如果需要进行一个上下文切换根据不同移植平台，这个函数也不同 */
    portYIELD_FROM_ISR(xTaskWokenByReceive);
}

读取但不移除队列项

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


// 带有中断保护的版本xQueuePeekFromIS()来完成相同功能。
BaseType_t xQueuePeekFromISR(QueueHandle_t xQueue, void *pvBuffer,);

描述：从队列中读取一个队列项，但不会把该队列项从队列中移除。

参数解析：同xQueueReceive()。

返回值：成功接收到列表项返回pdTRUE，否则返回pdFALSE。

向队尾覆盖投递队列项

BaseType_t xQueueOverwrite(QueueHandle_t xQueue, 
                           const void * pvItemToQueue);

//带有中断保护的版本
BaseType_t xQueueOverwriteFromISR (QueueHandle_t xQueue, 
                                   const void * pvItemToQueue,
                                   BaseType_t *pxHigherPriorityTaskWoken);

描述：向队列尾投递一个队列项，如果队列已满，则覆盖之前的队列项。

一般用于只有一个队列项的队列中，如果队列的队列项超过1个，使用这个宏会触发一个断言（已经正确定义configASSERT()的情况下）。

参数解析：

• pvItemToQueue：指针，指向要入队的项目。要保存到队列中的项目字节数在队列创建时就已确定。因此要从指针pvItemToQueue指向的区域拷贝到队列存储区域的字节数，也已确定。
• pxHigherPriorityTaskWoken：如果入队导致一个任务解锁，并且解锁的任务优先级高于当前运行的任务，则该函数将*pxHigherPriorityTaskWoken设置成pdTRUE。如果xQueueSendFromISR()设置这个值为pdTRUE，则中断退出前需要一次上下文切换。从FreeRTOS V7.3.0起，pxHigherPriorityTaskWoken称为一个可选参数，并可以设置为NULL。

例子：

void vFunction( void *pvParameters )
{
    QueueHandle_t xQueue;
    unsigned long ulVarToSend, ulValReceived;
 
    /*创建队列，保存一个unsignedlong值。如果一个队列的队列项超过1个，强烈建议不要使用xQueueOverwrite()，如果使用xQueueOverwrite()会触发一个断言（已经正确定义configASSERT()的情况下）。*/
    xQueue = xQueueCreate( 1, sizeof( unsigned long ) );
 
    /*使用 xQueueOverwrite().向队列写入10*/
    ulVarToSend = 10;
    xQueueOverwrite( xQueue, &ulVarToSend );
 
    /*从队列读取值，但是不把这个值从队列中删除。*/
    ulValReceived = 0;
    xQueuePeek( xQueue, &ulValReceived, 0 );
 
    if( ulValReceived != 10 )
     {
          /* 处理错误*/
     }
 
     /*到这里队列仍是满的。使用xQueueOverwrite()覆写队列，写入值100 */
     ulVarToSend = 100;
     xQueueOverwrite( xQueue, &ulVarToSend );
 
     /* 从队列中读取值*/
     xQueueReceive( xQueue, &ulValReceived, 0 );
 
     if( ulValReceived != 100 )
     {
          /*处理错误 */
     }
 
      /* ... */
}

调试

仅当你想使用可视化调试内核时，才进行队列和信号量注册。

宏configQUEUE_REGISTRY_SIZE定义了可以注册的队列和信号量的最大数量。

队列注册有两个目的，这两个目的都是为了调试RTOS内核：

• 它允许队列具有一个相关的文本名字，在GUI调试中可以容易的标识队列；
• 结合调试器用于定位每一个已经注册的队列和信号量时所需的信息。

队列注册

void vQueueAddToRegistry(QueueHandle_t xQueue, char *pcQueueName,);

描述：为队列分配名字并进行注册。

例子：

void vAFunction( void )
{
    xQueueHandle xQueue;
 
   /*创建一个队列，可以容纳10个char类型数值 */
   xQueue = xQueueCreate( 10, sizeof( portCHAR ) );
 
   /* 我们想可视化调试，所以注册它*/
   vQueueAddToRegistry( xQueue, "AMeaningfulName" );
}

解除注册

void vQueueUnregisterQueue(QueueHandle_t xQueue);

描述：从队列注册表中移除指定的队列。