FreeRTOS系列第18篇---FreeRTOS队列API函数

拼搏现实的明天。 2022-08-20 15:13 204阅读 0赞

FreeRTOS为操作队列提供了非常丰富的API函数，包括队列的创建、删除，灵活的入队和出队方式、带中断保护的入队和出队等等。下面就来详细讲述这些API函数。

### 1.获取队列入队信息数目 ###

#### **1.1函数描述** ####

UBaseType\_t uxQueueMessagesWaiting( QueueHandle\_t xQueue );

返回队列中存储的信息数目。具有中断保护的版本为uxQueueMessagesWaitingFromISR()，原型为：UBaseType\_t uxQueueMessagesWaitingFromISR( const QueueHandle\_t xQueue )。

#### **1.2参数描述** ####

*   xQueue：队列句柄

### 2.获取队列的空闲数目 ###

#### **2.1函数描述** ####

UBaseType\_t uxQueueSpacesAvailable( QueueHandle\_t xQueue );

返回队列的空闲数目。

#### **2.2参数描述** ####

*   xQueue：队列句柄

### 3.删除队列 ###

#### **3.1函数描述** ####

void vQueueDelete( QueueHandle\_t xQueue );

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

**3.2参数描述**

*   xQueue：队列句柄

### 4.复位队列 ###

#### **4.1函数描述** ####

BaseType\_t xQueueReset( QueueHandle\_t xQueue );

将队列复位到初始状态。

#### **4.2参数描述** ####

*   xQueue：队列句柄

#### **4.3返回值** ####

FreeRTOSV7.2.0以及以后的版本总是返回pdPASS。

### 5.创建队列 ###

#### **5.1函数描述** ####

QueueHandle\_t xQueueCreate (UBaseType\_t uxQueueLength, UBaseType\_t uxItemSize);

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

#### **5.2参数描述** ####

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

#### **5.3返回值** ####

成功创建队列返回队列句柄，否自返回0。

#### **5.4用法举例** ####

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 )
         {
             // 队列创建失败，不可以使用
         }
         // ... 任务的其它代码.
     }

### 6.向队列投递队列项 ###

#### 6.1 函数描述 ####

BaseType\_t xQueueSend(QueueHandle\_t xQueue, const void \* pvItemToQueue, TickType\_t xTicksToWait );

其实是一个宏，真正被调用的函数是xQueueGenericSend()。定义这个宏是为了向后兼容那些不包含函数xQueueSendToFront()和xQueueSendToBack()宏的FreeRTOS版本。它与xQueueSendToBack()等同。

这个宏向队列尾部投递一个队列项。项目以拷贝的形式入队，而不是引用形式入队。绝不可以在中断服务例程中调用这个宏，使用带有中断保护的版本xQueueSendFromISR()来完成相同的功能。

6.2参数描述

*  xQueue：队列句柄。
 *  pvItemToQueue：指针，指向要入队的项目。要保存到队列中的项目字节数在队列创建时就已确定。因此要从指针pvItemToQueue指向的区域拷贝到队列存储区域的字节数，也已确定。
 *  xTicksToWait：如果队列满，任务等待队列空闲的最大时间。如果队列满并且xTicksToWait被设置成0，函数立刻返回。时间单位为系统节拍时钟周期，因此宏portTICK\_PERIOD\_MS可以用来辅助计算真实延时值。如果INCLUDE\_vTaskSuspend设置成1，并且指定延时为portMAX\_DELAY将引起任务无限阻塞（没有超时）。

#### 6.3返回值 ####

队列项入队成功返回pdTRUE，否则返回errQUEUE\_FULL。

#### 6.4用法举例 ####

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 );
        }
             //... 任务其余代码.
     }

### 7.向队列投递队列项（带中断保护） ###

#### 7.1函数描述 ####

BaseType_t xQueueSendFromISR (QueueHandle_t xQueue,
                   const void *pvItemToQueue,  BaseType_t *pxHigherPriorityTaskWoken);

其实是一个宏，真正被调用的函数是xQueueGenericSendFromISR()。这个宏是xQueueSend()的中断保护版本，用于中断服务程序，等价于xQueueSendToBackFromISR()。

在中断服务例程中向队列尾部投递一个队列项。

#### 7.2参数描述 ####

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

#### 7.3返回值 ####

列项入队成功返回pdTRUE，否则返回errQUEUE\_FULL。

#### 7.4用法举例 ####

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

### 8.向队列尾部投递队列项 ###

#### 8.1函数描述 ####

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

其实是一个宏，真正被调用的函数是xQueueGenericSend()。这个宏等价于xQueueSend()。

向队列尾投递一个队列项。绝不可以在中断中调用这个宏，可以使用带有中断保护的版本xQueueSendToBackFromISR ()来完成相同功能。

#### 8.2参数描述 ####

同xQueueSend()。

#### 8.3返回值 ####

同xQueueSend()。

#### 8.4用法举例 ####

同xQueueSend()。

### 9.向队列尾部投递队列项（带中断保护） ###

#### 9.1函数描述 ####

BaseType_t xQueueSendToBackFromISR (QueueHandle_t xQueue,
                const void *pvItemToQueue, BaseType_t *pxHigherPriorityTaskWoken );

其实是一个宏，真正被调用的函数是xQueueGenericSendFromISR()。这个宏是xQueueSendToBack()的中断保护版本，用于中断服务程序，等价于xQueueSendFromISR()。

在中断服务例程中向队列尾部投递一个队列项。

#### 9.2参数描述 ####

同QueueSendFromISR()。

#### 9.3返回值 ####

同QueueSendFromISR()。

#### 9.4用法举例 ####

同QueueSendFromISR()。

### 10.向队列首部投递队列项 ###

#### 10.1函数描述 ####

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

其实是一个宏，真正被调用的函数是xQueueGenericSend()。

这个宏向队列首部投递一个队列项。绝不可以在中断服务例程中调用这个宏，可以使用带有中断保护的版本xQueueSendToFrontFromISR ()来完成相同功能。

#### 10.2参数描述 ####

#### 10.3返回值 ####

队列项入队成功返回pdTRUE，否则返回errQUEUE\_FULL。

### 11.向队列首部投递队列项（带中断保护） ###

#### 11.1函数描述 ####

BaseType_t xQueueSendToFrontFromISR (QueueHandle_t xQueue,
                  const void *pvItemToQueue,BaseType_t *pxHigherPriorityTaskWoken);

其实是一个宏，真正被调用的函数是xQueueGenericSendFromISR()。这个宏是xQueueSendToFront ()的中断保护版本，用于中断服务程序。

#### 11.2参数描述 ####

#### 11.3返回值 ####

列项入队成功返回pdTRUE，否则返回errQUEUE\_FULL。

### 12.读取并移除队列项 ###

#### 12.1函数描述 ####

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

其实是一个宏，真正被调用的函数是xQueueGenericReceive()。

这个宏从队列中读取一个队列项并把该队列项从队列中删除。读取队列项是以拷贝的形式完成，而不是以引用的形式，因此必须提供足够大的缓冲区以便容纳队列项。参数pvBuffer指向这个缓冲区。

绝不可以在中断服务例程中调用这个宏，可以使用使用带有中断保护的版本xQueueReceiveFromISR来完成相同功能。

#### 12.2参数描述 ####

*  pxQueue：队列句柄。
 *  pvBuffer：指向一个缓冲区，用于拷贝接收到的列表项。
 *  xTicksToWait：要接收的项目队列为空时，允许任务最大阻塞时间。如果设置该参数为0，则表示即队列为空也立即返回。阻塞时间的单位是系统节拍周期，宏portTICK\_RATE\_MS可辅助计算真实阻塞时间。如果INCLUDE\_vTaskSuspend设置成1，并且阻塞时间设置成portMAX\_DELAY，将会引起任务无限阻塞（不会有超时）。

#### 12.3返回值 ####

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

#### 12.4用法举例 ####

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变量
            }
        }
       // ... 其它代码
     }

### 13读取并移除队列项（带中断保护） ###

#### 13.1函数描述 ####

BaseType_t xQueueReceiveFromISR (QueueHandle_t xQueue,
                  void *pvBuffer, BaseType_t *pxHigherPriorityTaskWoken);

从队列中读取一个队列项并把该队列项从队列中删除。功能与xQueueReceive()相同，用于中断服务函数。

#### 13.2参数描述 ####

*  pxQueue：队列句柄。
 *  pvBuffer：指向一个缓冲区，用于拷贝接收到的列表项。
 *  pxHigherPriorityTaskWoken：如果入队导致一个任务解锁，并且解锁的任务优先级高于当前运行的任务，则该函数将\*pxHigherPriorityTaskWoken设置成pdTRUE。如果xQueueSendFromISR()设置这个值为pdTRUE，则中断退出前需要一次上下文切换。从FreeRTOS V7.3.0起，pxHigherPriorityTaskWoken称为一个可选参数，并可以设置为NULL。

#### 13.3返回值 ####

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

#### 13.4用法举例 ####

xQueueHandle xQueue;
     
    /* 该函数创建一个队列并投递一些值 */
    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);
    }

### 14.读取但不移除队列项 ###

#### 14.1函数描述 ####

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

其实是一个宏，真正被调用的函数是xQueueGenericReceive()。

这个宏从队列中读取一个队列项，但不会把该队列项从队列中移除。这个宏绝不可以用在中断服务例程中，可以使用使用带有中断保护的版本xQueuePeekFromIS()来完成相同功能。

#### 14.2参数描述 ####

同xQueueReceive()。

#### 14.3返回值 ####

同xQueueReceive()。

#### 14.4用法举例 ####

同xQueueReceive()。

### 15.读取但不移除队列项（带中断保护） ###

#### 15.1函数描述 ####

BaseType\_t xQueuePeekFromISR(QueueHandle\_t xQueue, void \*pvBuffer,);

功能与xQueuePeek()相同，用于中断服务程序。

#### 15.2参数描述 ####

*  pxQueue：队列句柄。
 *  pvBuffer：指向一个缓冲区，用于拷贝接收到的列表项。

#### 15.3返回值 ####

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

### 16.队列注册 ###

#### 16.1函数描述 ####

void vQueueAddToRegistry(QueueHandle\_t xQueue, char \*pcQueueName,);

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

#### 16.2参数描述 ####

*  l xQueue：队列句柄
 *  l pcQueueName：分配给队列的名字。这仅是一个有助于调试的字符串。队列注册仅存储指向队列名字符串的指针，因此这个字符串必须是静态的（全局变量活着存储在ROM/Flash中），不可以定义到堆栈中。

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

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

队列注册仅用于调试器。

宏configQUEUE\_REGISTRY\_SIZE定义了可以注册的队列和信号量的最大数量。仅当你想使用可视化调试内核时，才进行队列和信号量注册。

#### 16.3用法举例 ####

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

### 17.解除注册 ###

#### 17.1函数描述 ####

void vQueueUnregisterQueue(QueueHandle\_t xQueue);

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

17.2参数描述

*  xQueue：队列句柄

### 18.查询队列是否为空（仅用于中断服务程序） ###

#### 18.1函数描述 ####

BaseType\_t xQueueIsQueueEmptyFromISR( const QueueHandle\_t xQueue );

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

#### 18.2参数描述 ####

*  xQueue：队列句柄

#### 18.3返回值 ####

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

### 19.查询队列是否满（仅用于中断服务程序） ###

#### 19.1函数描述 ####

BaseType\_t xQueueIsQueueFullFromISR( const QueueHandle\_t xQueue );

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

#### 19.2参数描述 ####

*  xQueue：队列句柄

#### 19.3返回值 ####

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

### 20.向队列尾部覆盖式投递队列项 ###

#### 20.1函数描述 ####

BaseType\_t xQueueOverwrite(QueueHandle\_t xQueue, const void \* pvItemToQueue);

其实是个宏，真正被调用的函数是xQueueGenericSend()。这个宏是xQueueSendToBack()的另一个版本，向队列尾投递一个队列项，如果队列已满，则覆盖之前的队列项。一般用于只有一个队列项的队列中，如果队列的队列项超过1个，使用这个宏会触发一个断言（已经正确定义configASSERT()的情况下）。这个宏绝不可以在中断服务程序中调用，可以使用使用带有中断保护的版本xQueueOverwriteFromISR()来完成相同功能。

#### 20.2参数描述 ####

*  xQueue：队列句柄。
 *  pvItemToQueue：指针，指向要入队的项目。要保存到队列中的项目字节数在队列创建时就已确定。因此要从指针pvItemToQueue指向的区域拷贝到队列存储区域的字节数，也已确定。

#### 20.3返回值 ####

总是返回pdPASS。

#### 20.4用法举例 ####

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 )
         {
              /*处理错误 */
         }
     
          /* ... */
    }

### 21向队列尾部覆盖式投递队列项（带中断保护） ###

#### 21.1函数描述 ####

BaseType_t xQueueOverwriteFromISR (QueueHandle_t xQueue, const void * pvItemToQueue,
                                 BaseType_t *pxHigherPriorityTaskWoken);

其实是个宏，真正被调用的函数是xQueueGenericSendFromISR()。这个宏的功能与xQueueOverwrite()相同，用在中断服务程序中。

#### 21.2参数描述 ####

#### 21.3返回值 ####

总是返回pdPASS。