前言

FreeRTOS為操作隊(duì)列提供了非常豐富的API函數(shù)，包括隊(duì)列的創(chuàng)建、刪除，靈活的入隊(duì)和出隊(duì)方式、帶中斷保護(hù)的入隊(duì)和出隊(duì)等等。下面就來詳細(xì)講述這些API函數(shù)。

1.獲取隊(duì)列入隊(duì)信息數(shù)目

1.1函數(shù)描述

UBaseType_t uxQueueMessagesWaiting( QueueHandle_t xQueue );

返回隊(duì)列中存儲(chǔ)的信息數(shù)目。具有中斷保護(hù)的版本為uxQueueMessagesWaitingFromISR()，原型為：UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue )。

1.2參數(shù)描述

xQueue：隊(duì)列句柄

2.獲取隊(duì)列的空閑數(shù)目

2.1函數(shù)描述

UBaseType_t uxQueueSpacesAvailable( QueueHandle_t xQueue );

返回隊(duì)列的空閑數(shù)目。

2.2參數(shù)描述

xQueue：隊(duì)列句柄

3.刪除隊(duì)列

3.1函數(shù)描述

void vQueueDelete( QueueHandle_t xQueue );

刪除隊(duì)列并釋放所有分配給隊(duì)列的內(nèi)存。

3.2參數(shù)描述

xQueue：隊(duì)列句柄

4.復(fù)位隊(duì)列

4.1函數(shù)描述

BaseType_t xQueueReset( QueueHandle_t xQueue );

將隊(duì)列復(fù)位到初始狀態(tài)。

4.2參數(shù)描述

xQueue：隊(duì)列句柄

4.3返回值

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

5.創(chuàng)建隊(duì)列

5.1函數(shù)描述

QueueHandle_t xQueueCreate (UBaseType_t uxQueueLength, UBaseType_t uxItemSize);

創(chuàng)建新隊(duì)列。為新隊(duì)列分配指定的存儲(chǔ)空間并返回隊(duì)列句柄。

5.2參數(shù)描述

usQueueLength：隊(duì)列項(xiàng)數(shù)目

uxItemSize：每個(gè)隊(duì)列項(xiàng)大小，單位是字節(jié)。隊(duì)列項(xiàng)通過拷貝入隊(duì)而不是通過引用入隊(duì)，因此需要隊(duì)列項(xiàng)的大小。每個(gè)隊(duì)列項(xiàng)的大小必須相同。

5.3返回值

成功創(chuàng)建隊(duì)列返回隊(duì)列句柄，否自返回0。

5.4用法舉例

 struct AMessage
 {
     portCHAR ucMessageID;
     portCHAR ucData[ 20 ];
 };
 void vATask( void*pvParameters )
 {
     xQueueHandle xQueue1, xQueue2;
     // 創(chuàng)建一個(gè)隊(duì)列，隊(duì)列能包含10個(gè)unsigned long類型的值。
     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ));
     if( xQueue1 ==0 )
     {
         // 隊(duì)列創(chuàng)建失敗，不可以使用
     }
     // 創(chuàng)建一個(gè)隊(duì)列，隊(duì)列能包含10個(gè) Amessage結(jié)構(gòu)體指針類型的值。
     // 這樣可以通過傳遞指針變量來包含大量數(shù)據(jù)。
     xQueue2 =xQueueCreate( 10, sizeof( struct AMessage * ) );
     if( xQueue2 ==0 )
     {
         // 隊(duì)列創(chuàng)建失敗，不可以使用
     }
     // ... 任務(wù)的其它代碼.
 }

6.向隊(duì)列投遞隊(duì)列項(xiàng)

6.1 函數(shù)描述

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

其實(shí)是一個(gè)宏，真正被調(diào)用的函數(shù)是xQueueGenericSend()。定義這個(gè)宏是為了向后兼容那些不包含函數(shù)xQueueSendToFront()和xQueueSendToBack()宏的FreeRTOS版本。它與xQueueSendToBack()等同。

這個(gè)宏向隊(duì)列尾部投遞一個(gè)隊(duì)列項(xiàng)。項(xiàng)目以拷貝的形式入隊(duì)，而不是引用形式入隊(duì)。絕不可以在中斷服務(wù)例程中調(diào)用這個(gè)宏，使用帶有中斷保護(hù)的版本xQueueSendFromISR()來完成相同的功能。

6.2參數(shù)描述

xQueue：隊(duì)列句柄。

pvItemToQueue：指針，指向要入隊(duì)的項(xiàng)目。要保存到隊(duì)列中的項(xiàng)目字節(jié)數(shù)在隊(duì)列創(chuàng)建時(shí)就已確定。因此要從指針pvItemToQueue指向的區(qū)域拷貝到隊(duì)列存儲(chǔ)區(qū)域的字節(jié)數(shù)，也已確定。

xTicksToWait：如果隊(duì)列滿，任務(wù)等待隊(duì)列空閑的最大時(shí)間。如果隊(duì)列滿并且xTicksToWait被設(shè)置成0，函數(shù)立刻返回。時(shí)間單位為系統(tǒng)節(jié)拍時(shí)鐘周期，因此宏portTICK_PERIOD_MS可以用來輔助計(jì)算真實(shí)延時(shí)值。如果INCLUDE_vTaskSuspend設(shè)置成1，并且指定延時(shí)為portMAX_DELAY將引起任務(wù)無限阻塞（沒有超時(shí)）。

6.3返回值

隊(duì)列項(xiàng)入隊(duì)成功返回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;
     /*創(chuàng)建一個(gè)隊(duì)列，隊(duì)列能包含10個(gè)unsigned long類型的值。*/
     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );
     /* 創(chuàng)建一個(gè)隊(duì)列，隊(duì)列能包含10個(gè) Amessage結(jié)構(gòu)體指針類型的值。
       這樣可以通過傳遞指針變量來包含大量數(shù)據(jù)。*/
     xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
     // ...
     if( xQueue1 != 0 )
     {
          /*1個(gè)unsigned long型數(shù)據(jù)入隊(duì).如果需要等待隊(duì)列空間變的有效，
         會(huì)最多等待10個(gè)系統(tǒng)節(jié)拍周期*/
          if( xQueueSend( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) !=pdPASS )
          {
               /*消息入隊(duì)失敗*/
          }
    }
    if( xQueue2 != 0 )
    {
         /* 發(fā)送一個(gè)指向結(jié)構(gòu)體Amessage的對(duì)象，如果隊(duì)列滿也不等待 */
         pxMessage = & xMessage;
         xQueueSend( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 );
    }
         //... 任務(wù)其余代碼.
 }

7.向隊(duì)列投遞隊(duì)列項(xiàng)（帶中斷保護(hù)）

7.1函數(shù)描述

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

其實(shí)是一個(gè)宏，真正被調(diào)用的函數(shù)是xQueueGenericSendFromISR()。這個(gè)宏是xQueueSend()的中斷保護(hù)版本，用于中斷服務(wù)程序，等價(jià)于xQueueSendToBackFromISR()。

在中斷服務(wù)例程中向隊(duì)列尾部投遞一個(gè)隊(duì)列項(xiàng)。

7.2參數(shù)描述

xQueue：隊(duì)列句柄。

pvItemToQueue：指針，指向要入隊(duì)的項(xiàng)目。要保存到隊(duì)列中的項(xiàng)目字節(jié)數(shù)在隊(duì)列創(chuàng)建時(shí)就已確定。因此要從指針pvItemToQueue指向的區(qū)域拷貝到隊(duì)列存儲(chǔ)區(qū)域的字節(jié)數(shù)，也已確定。

pxHigherPriorityTaskWoken：如果入隊(duì)導(dǎo)致一個(gè)任務(wù)解鎖，并且解鎖的任務(wù)優(yōu)先級(jí)高于當(dāng)前運(yùn)行的任務(wù)，則該函數(shù)將*pxHigherPriorityTaskWoken設(shè)置成pdTRUE。如果xQueueSendFromISR()設(shè)置這個(gè)值為pdTRUE，則中斷退出前需要一次上下文切換。

從FreeRTOS V7.3.0起，pxHigherPriorityTaskWoken稱為一個(gè)可選參數(shù)，并可以設(shè)置為NULL。

7.3返回值

列項(xiàng)入隊(duì)成功返回pdTRUE，否則返回errQUEUE_FULL。

7.4用法舉例

void vBufferISR( void )
{
    portCHARcIn;
    portBASE_TYPE xHigherPriorityTaskWoken;
    /* 初始化，沒有喚醒任務(wù)*/
    xHigherPriorityTaskWoken = pdFALSE;
 
    /* 直到緩沖區(qū)為空 */
    do
    {
        /* 從緩沖區(qū)獲得一個(gè)字節(jié)數(shù)據(jù) */
        cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                                      
        /* 投遞這個(gè)數(shù)據(jù) */
        xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
    }while( portINPUT_BYTE( BUFFER_COUNT ) );
    /* 這里緩沖區(qū)已空，如果需要進(jìn)行一個(gè)上下文切換*/
    /*根據(jù)不同移植平臺(tái)，這個(gè)函數(shù)也不同*/
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

8.向隊(duì)列尾部投遞隊(duì)列項(xiàng)

8.1函數(shù)描述

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

其實(shí)是一個(gè)宏，真正被調(diào)用的函數(shù)是xQueueGenericSend()。這個(gè)宏等價(jià)于xQueueSend()。

向隊(duì)列尾投遞一個(gè)隊(duì)列項(xiàng)。絕不可以在中斷中調(diào)用這個(gè)宏，可以使用帶有中斷保護(hù)的版本xQueueSendToBackFromISR ()來完成相同功能。

8.2參數(shù)描述

同xQueueSend()。

8.3返回值

同xQueueSend()。

8.4用法舉例

同xQueueSend()。

9.向隊(duì)列尾部投遞隊(duì)列項(xiàng)（帶中斷保護(hù)）

9.1函數(shù)描述

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

其實(shí)是一個(gè)宏，真正被調(diào)用的函數(shù)是xQueueGenericSendFromISR()。這個(gè)宏是xQueueSendToBack()的中斷保護(hù)版本，用于中斷服務(wù)程序，等價(jià)于xQueueSendFromISR()。

在中斷服務(wù)例程中向隊(duì)列尾部投遞一個(gè)隊(duì)列項(xiàng)。

9.2參數(shù)描述

同QueueSendFromISR()。

9.3返回值

同QueueSendFromISR()。

9.4用法舉例

同QueueSendFromISR()。

10.向隊(duì)列首部投遞隊(duì)列項(xiàng)

10.1函數(shù)描述

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

其實(shí)是一個(gè)宏，真正被調(diào)用的函數(shù)是xQueueGenericSend()。

這個(gè)宏向隊(duì)列首部投遞一個(gè)隊(duì)列項(xiàng)。絕不可以在中斷服務(wù)例程中調(diào)用這個(gè)宏，可以使用帶有中斷保護(hù)的版本xQueueSendToFrontFromISR ()來完成相同功能。

10.2參數(shù)描述

xQueue：隊(duì)列句柄。

pvItemToQueue：指針，指向要入隊(duì)的項(xiàng)目。要保存到隊(duì)列中的項(xiàng)目字節(jié)數(shù)在隊(duì)列創(chuàng)建時(shí)就已確定。因此要從指針pvItemToQueue指向的區(qū)域拷貝到隊(duì)列存儲(chǔ)區(qū)域的字節(jié)數(shù)，也已確定。

xTicksToWait：如果隊(duì)列滿，任務(wù)等待隊(duì)列空閑的最大時(shí)間。如果隊(duì)列滿并且xTicksToWait被設(shè)置成0，函數(shù)立刻返回。時(shí)間單位為系統(tǒng)節(jié)拍時(shí)鐘周期，因此宏portTICK_PERIOD_MS可以用來輔助計(jì)算真實(shí)延時(shí)值。如果INCLUDE_vTaskSuspend設(shè)置成1，并且指定延時(shí)為portMAX_DELAY將引起任務(wù)無限阻塞（沒有超時(shí)）。

10.3返回值

隊(duì)列項(xiàng)入隊(duì)成功返回pdTRUE，否則返回errQUEUE_FULL。

11.向隊(duì)列首部投遞隊(duì)列項(xiàng)（帶中斷保護(hù)）

11.1函數(shù)描述

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

其實(shí)是一個(gè)宏，真正被調(diào)用的函數(shù)是xQueueGenericSendFromISR()。這個(gè)宏是xQueueSendToFront ()的中斷保護(hù)版本，用于中斷服務(wù)程序。

11.2參數(shù)描述

xQueue：隊(duì)列句柄。

pvItemToQueue：指針，指向要入隊(duì)的項(xiàng)目。要保存到隊(duì)列中的項(xiàng)目字節(jié)數(shù)在隊(duì)列創(chuàng)建時(shí)就已確定。因此要從指針pvItemToQueue指向的區(qū)域拷貝到隊(duì)列存儲(chǔ)區(qū)域的字節(jié)數(shù)，也已確定。

pxHigherPriorityTaskWoken：如果入隊(duì)導(dǎo)致一個(gè)任務(wù)解鎖，并且解鎖的任務(wù)優(yōu)先級(jí)高于當(dāng)前運(yùn)行的任務(wù)，則該函數(shù)將*pxHigherPriorityTaskWoken設(shè)置成pdTRUE。如果xQueueSendFromISR()設(shè)置這個(gè)值為pdTRUE，則中斷退出前需要一次上下文切換。從FreeRTOS V7.3.0起，pxHigherPriorityTaskWoken稱為一個(gè)可選參數(shù)，并可以設(shè)置為NULL。

11.3返回值

列項(xiàng)入隊(duì)成功返回pdTRUE，否則返回errQUEUE_FULL。

12.讀取并移除隊(duì)列項(xiàng)

12.1函數(shù)描述

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

其實(shí)是一個(gè)宏，真正被調(diào)用的函數(shù)是xQueueGenericReceive()。

這個(gè)宏從隊(duì)列中讀取一個(gè)隊(duì)列項(xiàng)并把該隊(duì)列項(xiàng)從隊(duì)列中刪除。讀取隊(duì)列項(xiàng)是以拷貝的形式完成，而不是以引用的形式，因此必須提供足夠大的緩沖區(qū)以便容納隊(duì)列項(xiàng)。參數(shù)pvBuffer指向這個(gè)緩沖區(qū)。

絕不可以在中斷服務(wù)例程中調(diào)用這個(gè)宏，可以使用使用帶有中斷保護(hù)的版本xQueueReceiveFromISR來完成相同功能。

12.2參數(shù)描述

pxQueue：隊(duì)列句柄。

pvBuffer：指向一個(gè)緩沖區(qū)，用于拷貝接收到的列表項(xiàng)。

xTicksToWait：要接收的項(xiàng)目隊(duì)列為空時(shí)，允許任務(wù)最大阻塞時(shí)間。如果設(shè)置該參數(shù)為0，則表示即隊(duì)列為空也立即返回。阻塞時(shí)間的單位是系統(tǒng)節(jié)拍周期，宏portTICK_RATE_MS可輔助計(jì)算真實(shí)阻塞時(shí)間。如果INCLUDE_vTaskSuspend設(shè)置成1，并且阻塞時(shí)間設(shè)置成portMAX_DELAY，將會(huì)引起任務(wù)無限阻塞（不會(huì)有超時(shí)）。

12.3返回值

成功接收到列表項(xiàng)返回pdTRUE，否則返回pdFALSE。

12.4用法舉例

struct AMessage
{
    portCHAR ucMessageID;
    portCHAR ucData[ 20 ];
} xMessage;
xQueueHandle xQueue;
// 創(chuàng)建一個(gè)隊(duì)列并投遞一個(gè)值
void vATask( void *pvParameters )
{
     struct AMessage *pxMessage;
     // 創(chuàng)建一個(gè)隊(duì)列，隊(duì)列能包含10個(gè) Amessage結(jié)構(gòu)體指針類型的值。
     // 這樣可以通過傳遞指針變量來包含大量數(shù)據(jù)。
     xQueue =xQueueCreate( 10, sizeof( struct AMessage * ) );
     if( xQueue == 0)
     {
          // 創(chuàng)建隊(duì)列失敗
    }
    // ...
    // 向隊(duì)列發(fā)送一個(gè)指向結(jié)構(gòu)體對(duì)象Amessage的指針，如果隊(duì)列滿不等待
    pxMessage = & xMessage;
    xQueueSend(xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );
    // ... 其它代碼
}
// 該任務(wù)從隊(duì)列中接收一個(gè)隊(duì)列項(xiàng)
voidvADifferentTask( void *pvParameters )
{
    struct AMessage *pxRxedMessage;
 
    if( xQueue != 0)
    {
        // 從創(chuàng)建的隊(duì)列中接收一個(gè)消息，如果消息無效，最多阻塞10個(gè)系統(tǒng)節(jié)拍周期
        if(xQueueReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )
        {
            // 現(xiàn)在pcRxedMessage 指向由vATask任務(wù)投遞進(jìn)來的結(jié)構(gòu)體Amessage變量
        }
    }
   // ... 其它代碼
 }

13讀取并移除隊(duì)列項(xiàng)（帶中斷保護(hù)）

13.1函數(shù)描述

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

從隊(duì)列中讀取一個(gè)隊(duì)列項(xiàng)并把該隊(duì)列項(xiàng)從隊(duì)列中刪除。功能與xQueueReceive()相同，用于中斷服務(wù)函數(shù)。

13.2參數(shù)描述

pxQueue：隊(duì)列句柄。

pvBuffer：指向一個(gè)緩沖區(qū)，用于拷貝接收到的列表項(xiàng)。

pxHigherPriorityTaskWoken：如果入隊(duì)導(dǎo)致一個(gè)任務(wù)解鎖，并且解鎖的任務(wù)優(yōu)先級(jí)高于當(dāng)前運(yùn)行的任務(wù)，則該函數(shù)將*pxHigherPriorityTaskWoken設(shè)置成pdTRUE。如果xQueueSendFromISR()設(shè)置這個(gè)值為pdTRUE，則中斷退出前需要一次上下文切換。從FreeRTOS V7.3.0起，pxHigherPriorityTaskWoken稱為一個(gè)可選參數(shù)，并可以設(shè)置為NULL。

13.3返回值

成功接收到列表項(xiàng)返回pdTRUE，否則返回pdFALSE。

13.4用法舉例

xQueueHandle xQueue;
/* 該函數(shù)創(chuàng)建一個(gè)隊(duì)列并投遞一些值 */
voidvAFunction( void *pvParameters )
{
     portCHAR cValueToPost;
     const portTickType xBlockTime = (portTickType )0xff;
     /*創(chuàng)建一個(gè)隊(duì)列，可以容納10個(gè)portCHAR型變量 */
     xQueue = xQueueCreate( 10, sizeof( portCHAR ) );
     if( xQueue == 0 )
     {
          /* 隊(duì)列創(chuàng)建失敗 */
     }
    /*…... */
    /* 投遞一些字符，在ISR中使用。如果隊(duì)列滿，任務(wù)將會(huì)阻塞xBlockTime 個(gè)系統(tǒng)節(jié)拍周期 */
    cValueToPost = 'a';
    xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
    cValueToPost = 'b';
    xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
    /*... 繼續(xù)投遞字符 ... 當(dāng)隊(duì)列滿時(shí)，這個(gè)任務(wù)會(huì)阻塞*/
    cValueToPost = 'c';
    xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
}
/* ISR：輸出從隊(duì)列接收到的所有字符 */
voidvISR_Routine( void )
{
     portBASE_TYPE xTaskWokenByReceive = pdFALSE;
     portCHAR cRxedChar;
     while( xQueueReceiveFromISR( xQueue, ( void *) &cRxedChar, &xTaskWokenByReceive) )
    {
       /* 接收到一個(gè)字符串，輸出.*/
       vOutputCharacter( cRxedChar );
       /* 如果從隊(duì)列移除一個(gè)字符串后喚醒了向此隊(duì)列投遞字符的任務(wù)，那么參數(shù)xTaskWokenByReceive將會(huì)設(shè)置成pdTRUE，這個(gè)循環(huán)無論重復(fù)多少次，僅會(huì)
          有一個(gè)任務(wù)被喚醒。*/
    }
    /*這里緩沖區(qū)已空，如果需要進(jìn)行一個(gè)上下文切換根據(jù)不同移植平臺(tái)，這個(gè)函數(shù)也不同 */
    portYIELD_FROM_ISR(xTaskWokenByReceive);
}

14.讀取但不移除隊(duì)列項(xiàng)

14.1函數(shù)描述

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

其實(shí)是一個(gè)宏，真正被調(diào)用的函數(shù)是xQueueGenericReceive()。

這個(gè)宏從隊(duì)列中讀取一個(gè)隊(duì)列項(xiàng)，但不會(huì)把該隊(duì)列項(xiàng)從隊(duì)列中移除。這個(gè)宏絕不可以用在中斷服務(wù)例程中，可以使用使用帶有中斷保護(hù)的版本xQueuePeekFromIS()來完成相同功能。

14.2參數(shù)描述

同xQueueReceive()。

14.3返回值

同xQueueReceive()。

14.4用法舉例

同xQueueReceive()。

15.讀取但不移除隊(duì)列項(xiàng)（帶中斷保護(hù)）

15.1函數(shù)描述

BaseType_t xQueuePeekFromISR(QueueHandle_t xQueue, void *pvBuffer,);

功能與xQueuePeek()相同，用于中斷服務(wù)程序。

15.2參數(shù)描述

pxQueue：隊(duì)列句柄。pvBuffer：指向一個(gè)緩沖區(qū)，用于拷貝接收到的列表項(xiàng)。

15.3返回值

成功接收到列表項(xiàng)返回pdTRUE，否則返回pdFALSE。

16.隊(duì)列注冊(cè)

16.1函數(shù)描述

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

為隊(duì)列分配名字并進(jìn)行注冊(cè)。

16.2參數(shù)描述

xQueue：隊(duì)列句柄

pcQueueName：分配給隊(duì)列的名字。這僅是一個(gè)有助于調(diào)試的字符串。隊(duì)列注冊(cè)僅存儲(chǔ)指向隊(duì)列名字符串的指針，因此這個(gè)字符串必須是靜態(tài)的（全局變量活著存儲(chǔ)在ROM/Flash中），不可以定義到堆棧中。

隊(duì)列注冊(cè)有兩個(gè)目的，這兩個(gè)目的都是為了調(diào)試RTOS內(nèi)核：

它允許隊(duì)列具有一個(gè)相關(guān)的文本名字，在GUI調(diào)試中可以容易的標(biāo)識(shí)隊(duì)列；包含調(diào)試器用于定位每一個(gè)已經(jīng)注冊(cè)的隊(duì)列和信號(hào)量時(shí)所需的信息。

隊(duì)列注冊(cè)僅用于調(diào)試器。

宏configQUEUE_REGISTRY_SIZE定義了可以注冊(cè)的隊(duì)列和信號(hào)量的最大數(shù)量。僅當(dāng)你想使用可視化調(diào)試內(nèi)核時(shí)，才進(jìn)行隊(duì)列和信號(hào)量注冊(cè)。

16.3用法舉例

void vAFunction( void )
{
    xQueueHandle xQueue;
   /*創(chuàng)建一個(gè)隊(duì)列，可以容納10個(gè)char類型數(shù)值 */
   xQueue = xQueueCreate( 10, sizeof( portCHAR ) );
   /* 我們想可視化調(diào)試，所以注冊(cè)它*/
   vQueueAddToRegistry( xQueue, "AMeaningfulName" );
}

17.解除注冊(cè)

17.1函數(shù)描述

void vQueueUnregisterQueue(QueueHandle_t xQueue);

從隊(duì)列注冊(cè)表中移除指定的隊(duì)列。

17.2參數(shù)描述

xQueue：隊(duì)列句柄

18.查詢隊(duì)列是否為空（僅用于中斷服務(wù)程序）

18.1函數(shù)描述

BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue );

查詢隊(duì)列是否為空。這個(gè)函數(shù)僅用于ISR。

18.2參數(shù)描述

xQueue：隊(duì)列句柄

18.3返回值

隊(duì)列非空返回pdFALSE，其它值表示隊(duì)列為空。

19.查詢隊(duì)列是否滿（僅用于中斷服務(wù)程序）

19.1函數(shù)描述

BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue );

查詢隊(duì)列是否滿，僅用于ISR。

19.2參數(shù)描述

xQueue：隊(duì)列句柄

19.3返回值

隊(duì)列沒有滿返回pdFALSE，其它值表示隊(duì)列滿。

20.向隊(duì)列尾部覆蓋式投遞隊(duì)列項(xiàng)

20.1函數(shù)描述

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

其實(shí)是個(gè)宏，真正被調(diào)用的函數(shù)是xQueueGenericSend()。這個(gè)宏是xQueueSendToBack()的另一個(gè)版本，向隊(duì)列尾投遞一個(gè)隊(duì)列項(xiàng)，如果隊(duì)列已滿，則覆蓋之前的隊(duì)列項(xiàng)。一般用于只有一個(gè)隊(duì)列項(xiàng)的隊(duì)列中，如果隊(duì)列的隊(duì)列項(xiàng)超過1個(gè)，使用這個(gè)宏會(huì)觸發(fā)一個(gè)斷言（已經(jīng)正確定義configASSERT()的情況下）。這個(gè)宏絕不可以在中斷服務(wù)程序中調(diào)用，可以使用使用帶有中斷保護(hù)的版本xQueueOverwriteFromISR()來完成相同功能。

20.2參數(shù)描述

xQueue：隊(duì)列句柄。

pvItemToQueue：指針，指向要入隊(duì)的項(xiàng)目。要保存到隊(duì)列中的項(xiàng)目字節(jié)數(shù)在隊(duì)列創(chuàng)建時(shí)就已確定。因此要從指針pvItemToQueue指向的區(qū)域拷貝到隊(duì)列存儲(chǔ)區(qū)域的字節(jié)數(shù)，也已確定。

20.3返回值

總是返回pdPASS。

20.4用法舉例

void vFunction( void *pvParameters )
{
    QueueHandle_t xQueue;
    unsigned long ulVarToSend, ulValReceived;
    /*創(chuàng)建隊(duì)列，保存一個(gè)unsignedlong值。如果一個(gè)隊(duì)列的隊(duì)列項(xiàng)超過1個(gè)，強(qiáng)烈建議不要使用xQueueOverwrite()，如果使用xQueueOverwrite()會(huì)觸發(fā)一個(gè)斷言（已經(jīng)正確定義configASSERT()的情況下）。*/
    xQueue = xQueueCreate( 1, sizeof( unsigned long ) );
     /*使用 xQueueOverwrite().向隊(duì)列寫入10*/
    ulVarToSend = 10;
    xQueueOverwrite( xQueue, &ulVarToSend );
    /*從隊(duì)列讀取值，但是不把這個(gè)值從隊(duì)列中刪除。*/
    ulValReceived = 0;
    xQueuePeek( xQueue, &ulValReceived, 0 );
    if( ulValReceived != 10 )
     {
          /* 處理錯(cuò)誤*/
     }
     /*到這里隊(duì)列仍是滿的。使用xQueueOverwrite()覆寫隊(duì)列，寫入值100 */
     ulVarToSend = 100;
     xQueueOverwrite( xQueue, &ulVarToSend );
     /* 從隊(duì)列中讀取值*/
     xQueueReceive( xQueue, &ulValReceived, 0 );
     if( ulValReceived != 100 )
     {
          /*處理錯(cuò)誤 */
     }
      /* ... */
}

21向隊(duì)列尾部覆蓋式投遞隊(duì)列項(xiàng)（帶中斷保護(hù)）

21.1函數(shù)描述

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

其實(shí)是個(gè)宏，真正被調(diào)用的函數(shù)是xQueueGenericSendFromISR()。這個(gè)宏的功能與xQueueOverwrite()相同，用在中斷服務(wù)程序中。

21.2參數(shù)描述

xQueue：隊(duì)列句柄。

pvItemToQueue：指針，指向要入隊(duì)的項(xiàng)目。要保存到隊(duì)列中的項(xiàng)目字節(jié)數(shù)在隊(duì)列創(chuàng)建時(shí)就已確定。因此要從指針pvItemToQueue指向的區(qū)域拷貝到隊(duì)列存儲(chǔ)區(qū)域的字節(jié)數(shù)，也已確定。

pxHigherPriorityTaskWoken：如果入隊(duì)導(dǎo)致一個(gè)任務(wù)解鎖，并且解鎖的任務(wù)優(yōu)先級(jí)高于當(dāng)前運(yùn)行的任務(wù)，則該函數(shù)將*pxHigherPriorityTaskWoken設(shè)置成pdTRUE。如果xQueueSendFromISR()設(shè)置這個(gè)值為pdTRUE，則中斷退出前需要一次上下文切換。從FreeRTOS V7.3.0起，pxHigherPriorityTaskWoken稱為一個(gè)可選參數(shù)，并可以設(shè)置為NULL。

21.3返回值

總是返回pdPASS。

以上就是FreeRTOS實(shí)時(shí)操作系統(tǒng)隊(duì)列的API函數(shù)講解的詳細(xì)內(nèi)容，更多關(guān)于FreeRTOS隊(duì)列API函數(shù)的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論