【FreeRTOS學習04】小白都能懂的 Queue Management 消息隊列使用詳解

消息隊列作爲任務間同步扮演着必不可少的角色；

1 前言

任務之間的同步（同步就是任務之間做數據交互，或爲兩個任務之間的通訊），任務和中斷之間的同步都可以依靠消息隊列，從而實現異步處理，FreeRTOS的隊列採用FIFO（先進先出）緩衝區，具體如下圖所示；

2 xQUEUE

FreeRTOS消息隊列的實現主要是queue.c，需要包含頭文件queue.h，下面先看一下queue.c中的數據類型xQUEUE，源碼如下所示；

typedef struct QueueDefinition
{
	int8_t *pcHead;					/*< Points to the beginning of the queue storage area. */
	int8_t *pcTail;					/*< Points to the byte at the end of the queue storage area.  Once more byte is allocated than necessary to store the queue items, this is used as a marker. */
	int8_t *pcWriteTo;				/*< Points to the free next place in the storage area. */

	union							/* Use of a union is an exception to the coding standard to ensure two mutually exclusive structure members don't appear simultaneously (wasting RAM). */
	{
		int8_t *pcReadFrom;			/*< Points to the last place that a queued item was read from when the structure is used as a queue. */
		UBaseType_t uxRecursiveCallCount;/*< Maintains a count of the number of times a recursive mutex has been recursively 'taken' when the structure is used as a mutex. */
	} u;

	List_t xTasksWaitingToSend;		/*< List of tasks that are blocked waiting to post onto this queue.  Stored in priority order. */
	List_t xTasksWaitingToReceive;	/*< List of tasks that are blocked waiting to read from this queue.  Stored in priority order. */

	volatile UBaseType_t uxMessagesWaiting;/*< The number of items currently in the queue. */
	UBaseType_t uxLength;			/*< The length of the queue defined as the number of items it will hold, not the number of bytes. */
	UBaseType_t uxItemSize;			/*< The size of each items that the queue will hold. */

	volatile int8_t cRxLock;		/*< Stores the number of items received from the queue (removed from the queue) while the queue was locked.  Set to queueUNLOCKED when the queue is not locked. */
	volatile int8_t cTxLock;		/*< Stores the number of items transmitted to the queue (added to the queue) while the queue was locked.  Set to queueUNLOCKED when the queue is not locked. */

	#if( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
		uint8_t ucStaticallyAllocated;	/*< Set to pdTRUE if the memory used by the queue was statically allocated to ensure no attempt is made to free the memory. */
	#endif

	#if ( configUSE_QUEUE_SETS == 1 )
		struct QueueDefinition *pxQueueSetContainer;
	#endif

	#if ( configUSE_TRACE_FACILITY == 1 )
		UBaseType_t uxQueueNumber;
		uint8_t ucQueueType;
	#endif

} xQUEUE;

本文暫時不需要深入源碼，在queue.h的接口已經封裝得相當好，無需對細節太過於關注，下面會是對常用接口的使用的總結，如果英文好，直接看源碼中的函數註釋也是很好的選擇。

3 相關概念

3.1 數據結構

隊列可以保存有限個具有確定長度的數據單元。隊列可以保存的最大單元數目被稱爲隊列的“深度”。在隊列創建時需要設定其深度和每個單元的大小。通常情況下，隊列被作爲 FIFO(先進先出)使用，即數據由隊列尾寫入，從隊列首讀出。當然，由隊列首寫入也是可能的。往隊列寫入數據是通過字節拷貝把數據複製存儲到隊列中；從隊列讀出數據使得把
隊列中的數據拷貝刪除。¹ 如下圖所示；



注意
上面提到的數據單元可以是一個char或int類型的數，但是相對比較合理的設計是，封裝成一個合理的類，或者稱之爲結構體，可以明確當前數據單元的數據類型，數據來源（來自哪個任務）等等，因爲一個隊列可以被多個任務進行讀取和發送函數，這樣就避免了傳輸數據出現混淆的情況。通常設計是一個隊列被多個任務寫入數據，然後有一個任務讀取，暫時稱之爲多寫一讀，反之，多讀一寫則較少遇到。

3.2 收發數據堵塞

當某個任務試圖讀或者寫一個隊列時，其可以指定一個阻塞超時時間，

• 讀取：
  任務讀取數據時，在設置堵塞超時時間內，如果隊列爲空，該任務將保持阻塞狀態以等待隊列數據有效。當其它任務或中斷服務例程
  往其等待的隊列中寫入了數據，該任務將自動由阻塞態轉移爲就緒態。

• 寫入：如果隊列被多個任務寫入，那麼將導致多個任務堵塞以等待隊列有效，當隊列有效的時候，這些任務中的優先級最高的任務優先進入就緒態。

4 常用函數

FreeRTOS的消息隊列常用接口都封裝在queue.h中，通過宏定義統一將接口函數的命名風格整理得十分統一；具體如下圖所示；

這裏有兩種需要注意；

• 任務與任務之間同步：例如圖中①處的API適用於任務間同步；
  • xQueueSendToFront
  • xQueueSendToFront
  • xQueueSend
  • xQueueOverwrite
• 任務與中斷之間同步：圖中②處的API適用於任務於中斷間同步，xxxISR()後綴的函數都是FreeRTOS中保證了線程安全的；
  • xQueueSendToFrontFromISR
  • xQueueSendToBackFromISR
  • xQueueOverwriteFromISR
  • xQueueSendFromISR

4.1 創建隊列

• QueueHandle_t
  QueueHandle_t是一個void類型的指針變量，定義在queue.h中，具體如下；

/**
 * Type by which queues are referenced.  For example, a call to xQueueCreate()
 * returns an QueueHandle_t variable that can then be used as a parameter to
 * xQueueSend(), xQueueReceive(), etc.
 */
typedef void * QueueHandle_t;

基本上每個隊列函數都會使用這個變量，這裏我們統一稱爲隊列的句柄；

• xQueueCreate
  這個函數可以創建一個隊列，創建成功則會返回一個隊列句柄，如果創建失敗則返回NULL，其函數原型是xQueueGenericCreate，具體如下所示；

#define xQueueCreate( uxQueueLength, uxItemSize ) \
xQueueGenericCreate( ( uxQueueLength ), ( uxItemSize ), ( queueQUEUE_TYPE_BASE ) )

xQueueCreate如下所示；

 QueueHandle_t xQueueCreate(
							  UBaseType_t uxQueueLength,
							  UBaseType_t uxItemSize
						  );

參數	描述
uxQueueLength	隊列能夠存儲的最大單元數目，即隊列深度
uxItemSize	隊列中數據單元的長度，以字節爲單位
retval	NULL：創建失敗；否則爲創建成功

4.2 發送數據

下面都是從任務發送數據到隊列，

• xQueueSendToFront
  將數據發送至隊首，函數聲明如下；

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

• xQueueSendToBack
  將數據發送至隊尾，函數聲明如下；

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

• xQueueSend
  與xQueueSendToBack入隊順序相同，函數聲明如下所示；

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

具體的參數描述如下：

參數	描述
xQueue	創建隊列時返回的句柄
pvItemToQueue	需要從任務發送到隊列的數據
xTicksToWait	阻塞超時時間。如果在發送時隊列已滿，這個時間即是任務處於阻塞態等待隊列空間有效的最長等待時間。
retval	pdPass：發送數據成功 errQUEUE_FULL：無法寫入數據

關於xTicksToWait

• xTicksToWait設爲0 ，且隊列已滿，則xQueueSendToFront()與xQueueSendToBack()均會立即返回。阻塞時間是以系統心跳週期爲單位的，所以絕對時間取決於系統心跳頻率。常量 portTICK_RATE_MS 可以用來把心跳時間單位轉換爲毫秒時間單位。
• xTicksToWait 設置爲 portMAX_DELAY ， 並且在FreeRTOSConig.h 中設定 INCLUDE_vTaskSuspend 爲 1，那麼阻塞等待將沒有超時限制。

4.3 接收數據

• xQueueReceive
  xQueueReceive()用於從隊列中接收(讀取）數據單元。接收到的單元同時會從隊列
  中刪除。函數聲明如下；

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

• xQueuePeek
  xQueuePeek()也是從從隊列中接收數據單元，不同的是並不從隊列中刪出接收到的單元。 xQueuePeek()從隊列首接收到數據後，不會修改隊列中的數據，也不會改變數據在隊列中的存儲序順。函數聲明如下；

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

具體的參數描述如下：

參數	描述
xQueue	隊列的句柄
pvBuffer	接收緩存指針。其指向一段內存區域，用於接收從隊列中拷貝來的數據
xTicksToWait	阻塞超時時間
retavl	pdPASS：接收成功 errQUEUE_FULL：接收失敗

• uxQueueSpacesAvailable
  uxQueueSpacesAvailable()用於查詢隊列中可用的空閒空間數量；函數聲明如下；

UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue );

參數	描述
xQueue	隊列的句柄
retval	當前隊列中空餘的數據單元個數，0表示隊列已滿

• uxQueueMessagesWaiting
  uxQueueMessagesWaiting()用於查詢隊列中當前有效數據單元個數；函數聲明如下；

UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue );

參數	描述
xQueue	隊列的句柄
retval	當前隊列中空餘的數據單元個數，0表示隊列爲空

4.4 刪除隊列

• vQueueDelete
  用來刪除一個隊列，直接傳入已創建的隊列句柄即可，函數聲明如下；

void vQueueDelete( QueueHandle_t xQueue );

5 舉例

多個任務寫入一個任務讀取的時候應該怎麼做呢？如下圖所示²；

這裏有三個任務，所以爲了搞清楚數據來自哪個任務，因此將數據單元封裝起來，使用
iMeaning表示數據單元的源頭，當然這裏還是比較簡單的應用。

6 總結

本文介紹了FreeRTOS的消息隊列比價常用的方法，當然是相對簡單的，側重在瞭解概念上，需要實際的應用從而加深理解，更加詳細已經靈活的應用可以參考FreeRTOS作者撰寫的Mastering_the_FreeRTOS_Real_Time_Kernel-A_Hands-On_Tutorial_Guide。

---

1. Mastering_the_FreeRTOS_Real_Time_Kernel-A_Hands-On_Tutorial_Guide.pdf ↩︎

2. FREERTOS 實時內核實用指南,Zou Changjun ↩︎