一、任務建立

1. xTaskCreate

task. h 

portBASE_TYPE xTaskCreate( 

                            pdTASK_CODE pvTaskCode, 

                            const portCHAR * const pcName, 

                            unsigned portSHORT usStackDepth, 

                            void *pvParameters, 

                            unsigned portBASE_TYPE uxPriority, 

                            xTaskHandle *pvCreatedTask 

                          );

建立新的任務並新增到任務佇列中，準備執行 

Parameters: 

pvTaskCode	指向任務的入口函式. 任務必須執行並且永不返回 (即：無限迴圈).
pcName	描述任務的名字。主要便於除錯。最大長度由configMAX_TASK_NAME_LEN.定義
usStackDepth	指定任務堆疊的大小 ，堆疊能保護變數的數目- 不是位元組數. 例如，如果堆疊為16位寬度，usStackDepth定義為 100, 200 位元組，這些將分配給堆疊。堆疊巢狀深度（堆疊寬度）不能超多最大值——包含了size_t型別的變數
pvParameters	指標用於作為一個引數傳向建立的任務
uxPriority	任務執行時的優先順序
pvCreatedTask	用於傳遞一個處理——引用建立的任務

返回: pdPASS 是如果任務成功建立並且新增到就緒列中，另外錯誤程式碼在projdefs. H檔案定義

2. vTaskDelete

task. h 

void vTaskDelete( xTaskHandle pxTask );

INCLUDE_vTaskDelete必須定義為1，這個函式才能可用。檢視配置部分獲得更多資訊。 

從RTOS實時核心管理中移除任務。要刪除的任務將從就緒，封鎖，掛起，事件列表中移除。 

注意：空閒任務負責釋放核心分配給已刪除任務的記憶體。因此，如果應用程式呼叫了vTaskDelete ()，微控制器執行時間，空閒任務不假死是很重要的。記憶體分配給任務的程式碼不會自動釋放，應該在任務刪除之前。 

引數： 

pxTask

處理要刪除的任務。傳遞NULL將引起呼叫任務刪除

二、任務控制

3. vTaskDelay 

task. h 

void vTaskDelay( portTickType xTicksToDelay );

INCLUDE_vTaskDelay必須設定為1，這個函式才為可用。參考配置獲得更多資訊。 

延時任務為已知時間片。任務被鎖住剩餘的實際時間由時間片率決定。portTICK_RATE_MS常量用來用來從時間片速率（一片週期代表著解析度）來計算實際時間。 

vTaskDelay()指定一個任務希望的時間段，這個時間之後（呼叫vTaskDelay() ）任務解鎖。例如，指定週期段為100時間片，將使任務在呼叫vTaskDelay()100個時間片之後解鎖。vTaskDelay()不提供一個控制週期性任務頻率的好方法，像通過程式碼採取的路徑，和其他任務和中斷一樣，在呼叫vTaskDelay()後 影響頻率，因此任務所需的時間下一次執行。 

參考 vTaskDelayUntil() ，這個交替的API函式設計了執行固定的頻率。它是指定的一個絕對時間（而不是一個相對時間）後，呼叫任務解鎖。 

引數: 

xTicksToDelay

時間數量，呼叫任務應該鎖住的時間片週期

4. vTaskDelayUntil

task. h 

void vTaskDelayUntil( portTickType *pxPreviousWakeTime, portTickType xTimeIncrement );

INCLUDE_vTaskDelayUntil 必須定義為1，此函式才能用。參考配置獲得更多資訊。 

延時一個任務到指定時間。這個函式用在迴圈任務以確保一定頻率執行。這個函式在一個重要方面上不同於vTaskDelay()，vTaskDelay() 指定的這個時間（任務希望開啟）是與vTaskDelay() 有關，而vTaskDelayUntil() 指定是一個絕對時間（任務希望開啟） vTaskDelay()中斷任務從呼叫這個函式開始到指定時間。很難使用vTaskDelay()自身來產生一個固定的執行頻率，因為：隨著呼叫vTaskDelay()一個任務開啟的時間和任務下一次呼叫vTaskDelay()的時間，這兩者之間可能不是固定的【任務可能採取不同方式，可能通過呼叫，可能來自中斷，或者優先取得每次任務執行的時間】。 而vTaskDelay()指定的時間與呼叫這個函式相關，vTaskDelayUntil() 指定的是絕對時間(任務希望開啟的)。 

應該注意：vTaskDelayUntil() 如果指定的甦醒時間使用完，將立即返回。因此，一個使用vTaskDelayUntil() 來週期性的執行的任務，如果執行週期因為任何原因（例如任務是臨時為懸掛狀態）暫停而導致任務錯過一個或多個執行週期，那麼需要重新計算甦醒時間。通過檢查像pxPreviousWakeTime可變的引數來組織當前時間片計數。然而在大多數使用中並不是必須的。 產量 portTICK_RATE_MS 用來計算時間片頻率的實時時間- 按照一個時間片週期。 

引數： 

pxPreviousWakeTime	指定一個變數來掌握任務最後開啟的時間。這個變數在第一次使用中（參考下面的例子）必須使用當前時間來初始化。在vTaskDelayUntil()中，這個變數是自動修改的
xTimeIncrement	迴圈週期時間。任務將在一定時間開啟（*pxPreviousWakeTime + xTimeIncrement）。使用相同的xTimeIncrement引數值，來呼叫vTaskDelayUntil()將使任務按固定的週期執行。

5. uxTaskPriorityGet

task. h 

unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask );

設定INCLUDE_vTaskPriorityGet 為1，此函式才能用。參考配置以獲得更多資訊。 獲得任務的優先順序。 

引數： 

pxTask

需要處理的任務. 當傳遞NULL時，將返回所呼叫任務的優先順序

Returns: 

pxTask的優先順序

6. vTaskPrioritySet

task. h 

void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority );

設定INCLUDE_vTaskPrioritySet為1，才能使用此函式。參考配置獲得更多資訊。 設定任務的優先順序。 如果設定的優先順序高於當前執行任務的優先順序，則上下文切換將在此函式返回之前發生。 

引數： 

pxTask	需要設定優先順序的任務。當傳遞NULL，將設定呼叫任務的優先順序
uxNewPriority	任務需要設定的優先順序

7. vTaskSuspend 

task. h 

void vTaskSuspend( xTaskHandle pxTaskToSuspend );

設定INCLUDE_vTaskSuspend 為1，此函式才能使用。參考配置獲得更多資訊。 掛起任務，當掛起一個任務時，不管優先順序是多少，不需要佔用任何微控制器處理器時間。呼叫vTaskSuspend不會累積——即：在統一任務中呼叫vTaskSuspend兩次，但只需呼叫一次vTaskResume () 來是掛起的任務就緒。 

引數： 

pxTaskToSuspend

處理需要掛起的任務。傳遞NULL將掛起呼叫此函式的任務。

8. vTaskResume 

task. h 

void vTaskResume( xTaskHandle pxTaskToResume );

設定INCLUDE_vTaskSuspend為1，此函式才能使用。參考配置獲得更多資訊。 

喚醒掛起的任務。 必須是呼叫 vTaskSuspend () 後掛起的任務，才有可能通過呼叫 vTaskResume ()重新執行。 

Parameters: 

pxTaskToResume

就緒的任務的控制代碼

9. vTaskResumeFromISR

task. h 

portBASE_TYPE vTaskResumeFromISR( xTaskHandle pxTaskToResume );

設定INCLUDE_vTaskSuspend和INCLUDE_xTaskResumeFromISR都為1，才能使用此函式。參考配置獲得更過資訊。從ISR中喚醒掛起的任務。可能通過多個 呼叫vTaskSuspend()掛起的任務，可以通過呼叫 xTaskResumeFromISR()再次執行。vTaskResumeFromISR()不應該用於任務和中斷同步，因為可能會在中斷髮生期間，任務已經掛起——這樣導致錯過中斷。使用訊號量最為同步機制將避免這種偶然性。 

引數： 

pxTaskToResume

就緒任務的控制代碼

Returns: 

pdTRUE： 如果喚醒了任務將，引起上下文切換。 pdFALSE.：用於ISR確定是否上下文切換

10. vTaskSetApplicationTaskTag 

task. h 

void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxTagValue );

onfigUSE_APPLICATION_TASK_TAG必須定義為1，這個函式才能可用。參考配置獲得更多資訊。能為每個任務分配標籤值。這個值僅在應用程式中使用，核心本身不使用它。 RTOS trace macros文件提供了一個很好的例子——應用程式如何利用這個特點。 

引數: 

xTask	將分配給標籤值的任務。傳遞NULL將分配標籤給呼叫的任務。
pxTagValue	分配給任務的標籤值 型別為 pdTASK_HOOK_CODE ， 允許一個函式指標賦值給標籤。因此實際上任何值都可以分配。參考下面的例子。

xTaskCallApplicationTaskHook 

task. H

#define traceTASK_SWITCHED_OUT()   xTaskCallApplicationTaskHook( pxCurrentTCB, 0 )

portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, void *pvParameter );

configUSE_APPLICATION_TASK_TAG必須設定為1，這個函式才能使用。參考配置獲得更多資訊。 

每個任務可以分配一個標籤值。正常情況下，這個值僅用於應用程式，核心並不儲存。然而，可以使用標籤賦值給鉤子（或回撥）函式給任務——鉤子函式將通過呼叫xTaskCallApplicationTaskHook()執行。每個任務定義自己的返回值，或者僅僅定義一個返回值。儘管可以使用第一個函式引數來呼叫任務中的鉤子函式，最常見的使用是任務鉤子函式——描述鉤子巨集，像每個如下的例子。任務鉤子函式必須使用pdTASK_HOOK_CODE型別，傳遞void *引數，和返回portBASE_TYPE型別的值。Void *引數用來傳遞給鉤子函式的任何資訊。 

引數: 

xTask	處理將被呼叫鉤子函式的任務。xTask當作NULL傳遞，將呼叫鉤子函式賦值給當前執行的任務
pvParameter	傳遞給鉤子函式的值。可以是指向結構或數值的指標

三、核心控制

11. vTaskStartScheduler

task. h 

void vTaskStartScheduler( void );

啟動實時核心處理。在呼叫之後，核心已經控制執行的任務。當 vTaskStartScheduler() 被呼叫時，空閒任務自動建立。如果 vTaskStartScheduler() 成功呼叫，這個函式不返回，直到執行任務呼叫vTaskEndScheduler()。如果可供給空閒任務的RAM不足，那麼函式呼叫失敗，並立即返回。 

12. vTaskEndSchedule 

task. h 

void vTaskEndScheduler( void );

停止實時核心執行。所有建立的任務將自動刪除，並且多工（優先順序或合作式）將停止。當vTaskStartScheduler()呼叫時，執行將再次開始，像vTaskStartScheduler()僅僅返回。在演示或PC路徑的例子中，參考演示應用程式檔案main.c，例子中使用vTaskEndScheduler ()。vTaskEndScheduler ()需要在便攜層定義出口函式（參考在port.c提供PC介面的vPortEndScheduler () ）。執行硬體指定操作如停止核心執行。vPortEndScheduler () 導致所有由核心分配的資源釋放——但是不會釋放由應用程式的任務分配的資源。 

13. vTaskSuspendAll 

task. h 

void vTaskSuspendAll( void );

掛起所有活動的實時核心，同時允許中斷（包括核心滴答）。任務在呼叫vTaskSuspendAll ()後，這個任務將繼續執行，不會有任何被切換的危險，直到呼叫xTaskResumeAll ()函式。API中有可能影響影響上下文切換的函式（例如，vTaskDelayUntil(), xQueueSend()等等），一定不能再排程器掛起時被呼叫。

四、佇列管理 

14. xQueueCreate[佇列管理] 

queue. h 

xQueueHandle xQueueCreate( 

                            unsigned portBASE_TYPE uxQueueLength, 

                            unsigned portBASE_TYPE uxItemSize 

                          );

建立一個新的佇列。為新的佇列分配所需的儲存記憶體，並返回一個佇列處理。 

Parameters: 

uxQueueLength	佇列中包含最大專案數量。
uxItemSize	佇列中每個專案所需的位元組數。專案通過複製而不是引用排隊，因為，所需的位元組數，將複製給每個專案。佇列中每個專案必須分配同樣大小。

Returns: 

如果佇列成功建立，並返回一個新建佇列的處理。

如果不能建立佇列，將返回0。

15. xQueueSend[佇列管理] 

queue.h 

portBASE_TYPE xQueueSend( 

                            xQueueHandle xQueue, 

                            const void * pvItemToQueue, 

                            portTickType xTicksToWait 

                         );

是一個呼叫xQueueGenericSend()的巨集。能向後相容FreeRTOS.org（沒有包括xQueueSendToFront()和

xQueueSendToBack() 巨集的）版本。與xQueueSendToBack()等效。 傳遞一個專案到佇列。這個專案通過複製而不是通過引用排隊。這個函式不能從中斷服務程式呼叫。參考xQueueSendFromISR()，在ISR中交錯使用。xQueueSend() 是全特點任務間通訊API介面。xQueueSend() 等效於交叉API。版本不要同樣的引數和同樣的返回值。 

Parameters: 

xQueue	處理將專案傳遞給佇列
pvItemToQueue	指向佇列中放置的專案的指標。專案的大小，由佇列建立時定義，因為許多位元組可以從 pvItemToQueue複製到佇列的儲存區域
xTicksToWait	最大時間量（任務應該鎖住，等待佇列中的可用空間）應該已經滿了。如果設定為0，呼叫將立即返回。時間使用滴答週期來定義，因此如果需要，常量portTICK_RATE_MS應該用來轉換實時時間

Returns: 

pdTRUE：專案成功傳遞。

否則為：errQUEUE_FULL.

16. xQueueSendToBack[佇列管理] 

Only available from FreeRTOS.org V4.5.0 onwards. 

queue.h 

portBASE_TYPE xQueueSendToBack(

                                   xQueueHandle xQueue,

                                   const void * pvItemToQueue,

                                   portTickType xTicksToWait

                               );

是一個呼叫xQueueGenericSend()的巨集。相當於xQueueSend()。傳遞專案到一個佇列中的後面。這個項是複製佇列，不是引用。這個函式不能被中斷服務函式呼叫。參考xQueueSendToBackFromISR ()，可以在ISR中交替使用。 xQueueSendToBack()是全功能任務間通訊API介面。xQueueAltSendToBack()相當於API其中之一。版本需要相同的引數和相同的返回值 。 

引數: 

xQueue	將要傳進的佇列控制代碼
pvItemToQueue	指向將要放進佇列的專案。專案的大小由佇列定義（佇列建立時），許多位元組從 pvItemToQueue複製到佇列儲存區域
xTicksToWait	任務中斷並等待佇列中可用空間的最大時間，應該是滿的。如果設定為0，呼叫將立刻返回。時間在片區間中定義，如果需要，portTICK_RATE_MS常量用來轉換為實際時間。 如果定義為1 ，指定的中斷時間（ portMAX_DELAY） 將導致任務無限期中斷（沒有時間溢位）。

Returns: 

pdTRUE 如果任務成功傳遞。 

否則為 errQUEUE_FULL.

17. xQueueSendToFront[佇列管理] 

僅適用於FreeRTOS.org V4.5.0 以前版本 

queue.h 

portBASE_TYPE xQueueSendToToFront(

                                      xQueueHandle xQueue,

                                      const void * pvItemToQueue,

                                      portTickType xTicksToWait

                                  );

是一個呼叫xQueueGenericSend()的巨集。傳遞專案到一個佇列中的前面。這個項是複製佇列，不是引用。這個函式不能被中斷服務函式呼叫。參考xQueueSendToBackFromISR ()，可以在ISR中交替使用。xQueueSendToFront() 是全功能任務間通訊API介面。xQueueAltSendToFront() 相當於API其中之一。版本需要相同的引數和相同的返回值。 

Parameters: 

xQueue	將要傳進的佇列控制代碼
pvItemToQueue	指向將要放進佇列的專案。專案的大小由佇列定義（佇列建立時），許多位元組從 pvItemToQueue複製到佇列儲存區域
xTicksToWait	任務中斷並等待佇列中可用空間的最大時間，應該是滿的。如果設定為0，呼叫將立刻返回。時間在片區間中定義，如果需要，portTICK_RATE_MS常量用來轉換為實際時間。 如果  定義為1 ，指定的中斷時間（ portMAX_DELAY） 將導致任務無限期中斷（沒有時間溢位）。

Returns: 

pdTRUE 如果任務成功傳遞。 否則為 errQUEUE_FULL.

18. xQueueReceive[佇列管理] 

queue. h 

portBASE_TYPE xQueueReceive( 

                               xQueueHandle xQueue, 

                               void *pvBuffer, 

                               portTickType xTicksToWait 

                            );

一個呼叫 xQueueGenericReceive()函式的巨集。從佇列接收一個專案。這個專案通過複製接收，因此緩衝器必須提供足夠大的空間。複製進緩衝器的位元組數，在佇列建立時已經定義。這個函式一定不能在中斷服務程式中使用。參考xQueueReceiveFromISR獲得能夠的選擇。xQueueReceive()是全功能任務間通訊API介面。xQueueAltReceive() 相當於API其中之一。版本需要相同的引數和相同的返回值。 

引數： 

pxQueue	將要接收專案的佇列控制代碼
pvBuffer	指向將要複製接收專案的緩衝器的指標。
xTicksToWait	任務中斷並等待佇列中可用空間的最大時間，應該是滿的。如果設定為0，呼叫將立刻返回。時間在片區間中定義，如果需要，portTICK_RATE_MS常量用來轉換為實際時間。 如果 定義為1 ，指定的中斷時間（ portMAX_DELAY） 將導致任務無限期中斷（沒有時間溢位）。

Returns: 

如果專案成功被佇列接收為pdTRUE 。 否則為 pdFALSE.

19. xQueuePeek[佇列管理] 

Only available from FreeRTOS.org V4.5.0 onwards. 

queue.h 

portBASE_TYPE xQueuePeek(

                             xQueueHandle xQueue,

                             void *pvBuffer,

                             portTickType xTicksToWait

                         );

一個呼叫 xQueueGenericReceive()函式的巨集。從佇列接收一個專案並從佇列中移除該專案。這個專案通過複製接收，因此緩衝器必須提供足夠大的空間。複製進緩衝器的位元組數，在佇列建立時已經定義。成功接收的專案在佇列中保留，再下次呼叫時將再次返回，或者呼叫xQueueReceive() 這個函式一定不能在中斷服務程式中使用。 xQueuePeek() 是全功能任務間通訊API介面。xQueueAltPeek() 相當於API其中之一。版本需要相同的引數和相同的返回值。 

引數： 

xQueue	將要接收專案的佇列的控制代碼
pvBuffer	指向將要複製接收專案的緩衝器的指標。專案的大小由佇列定義（佇列建立時），許多位元組從 pvItemToQueue複製到佇列儲存區域
xTicksToWait	任務中斷並等待佇列中可用空間的最大時間，應該是滿的。如果設定為0，呼叫將立刻返回。時間在片區間中定義，如果需要，portTICK_RATE_MS常量用來轉換為實際時間。 如果  定義為1 ，指定的中斷時間（ portMAX_DELAY） 將導致任務無限期中斷（沒有時間溢位）。

返回值： 

pdTRUE 如果專案成功被佇列接收。 

否則為 pdFALSE.

20. xQueueSendFromISR[佇列管理] 

queue.h 

portBASE_TYPE xQueueSendFromISR( 

                                   xQueueHandle pxQueue, 

                                   const void *pvItemToQueue, 

                                   portBASE_TYPE *pxHigherPriorityTaskWoken

                                );

這是一個呼叫xQueueGenericSendFromISR()的巨集。是為了相容FreeRTOS.org以後的版本（沒有包含xQueueSendToBackFromISR() 和 xQueueSendToFrontFromISR() 巨集）傳遞一個項到佇列的後面。在終端服務程式中可以安全使用。項在佇列中是複製而不是引用，排列小專案更加靈活，特別是當從ISR呼叫時。在大多數情況下，使用一個指向專案的指標傳進佇列更加靈活 

引數: 

xQueue	將專案傳進的佇列
pvItemToQueue	一個指向將在佇列中放置的專案的指標。專案的大小，佇列在建立時已經定義了， 將從pvItemToQueue複製許多位元組到佇列的儲存區域
pxHigherPriorityTaskWoken	如果傳進佇列而導致任務解鎖，並且解鎖的任務的優先順序高於當前執行任務的優先順序xQueueSendFromISR將設定 *pxHigherPriorityTaskWoken到 pdTRUE 。如果xQueueSendFromISR()設定這個值到 pdTRUE，在中斷推出之前將請求任務切換。

Returns: 

pdTRUE：資料成功傳遞進佇列。

否則為：errQUEUE_FULL。使用範例是緩衝IO（每次呼叫ISR能夠更多的值）

21. xQueueSendToBackFromISR[佇列管理] 

queue.h 

portBASE_TYPE xQueueSendToBackFromISR( 

                                         xQueueHandle pxQueue, 

                                         const void *pvItemToQueue, 

                                         portBASE_TYPE *pxHigherPriorityTaskWoken

                                      );

這是一個呼叫 xQueueGenericSendFromISR()的巨集。是為了相容FreeRTOS.org以後的版本（沒有包含xQueueSendToBackFromISR() 和 xQueueSendToFrontFromISR() 巨集） 傳遞一個項到佇列的後面。在終端服務程式中可以安全使用。項在佇列中是複製而不是引用，排列小專案更加靈活，特別是當從ISR呼叫時。在大多數情況下，使用一個指向專案的指標傳進佇列更加靈活。. 

引數： 

xQueue	將專案傳進的佇列
pvItemToQueue	一個指向將在佇列中放置的專案的指標。專案的大小，佇列在建立時已經定義了， 將從pvItemToQueue複製許多位元組到佇列的儲存區域
xTaskPreviouslyWoken	如果傳進佇列而導致任務解鎖，並且解鎖的任務的優先順序高於當前執行任務的優先順序xQueueSendFromISR將設定 *pxHigherPriorityTaskWoken到 pdTRUE 。如果xQueueSendFromISR()設定這個值到 pdTRUE，在中斷推出之前將請求任務切換。

Returns: 

pdTRUE：資料成功傳遞進佇列。

否則為：errQUEUE_FULL。使用範例是緩衝IO（每次呼叫ISR能夠更多的值）

22. xQueueSendToFrontFromISR[佇列管理] 

queue.h 

portBASE_TYPE xQueueSendToFrontFromISR(

                                         xQueueHandle pxQueue,

                                         const void *pvItemToQueue,

                                         portBASE_TYPE *pxHigherPriorityTaskWoken

                                       );

是一個呼叫xQueueGenericSendFromISR().的巨集。傳遞一個項到佇列的後面。在終端服務程式中可以安全使用。 

項在佇列中是複製而不是引用，排列小專案更加靈活，特別是當從ISR呼叫時。 

引數： 

xQueue	將專案傳進的佇列
pvItemToQueue	一個指向將在佇列中放置的專案的指標。專案的大小，佇列在建立時已經定義了， 將從pvItemToQueue複製許多位元組到佇列的儲存區域
xTaskPreviouslyWoken	如果傳進佇列而導致任務解鎖，並且解鎖的任務的優先順序高於當前執行任務的優先順序xQueueSendTobackFromISR() 將設定 *pxHigherPriorityTaskWoken到 pdTRUE 。如果xQueueSendToBackFromISR()設定這個值到 pdTRUE，在中斷推出之前將請求任務切換。

Returns: 

pdTRUE：資料成功傳遞進佇列。否則為：errQUEUE_FULL。使用範例是緩衝IO（每次呼叫ISR能夠更多的值）

23. xQueueReceiveFromISR[佇列管理] 

queue. h 

portBASE_TYPE xQueueReceiveFromISR( 

                                       xQueueHandle pxQueue, 

                                       void *pvBuffer, 

                                       portBASE_TYPE *pxTaskWoken 

                                   ); 

從佇列接收一個專案。在中斷程式中使用此函式是安全的。 

Parameters: 

pxQueue	傳送專案的佇列控制代碼
pvBuffer	指向緩衝區的指標，將接收的專案被複制進去。
pxTaskWoken	任務將鎖住，等待佇列中的可用空間。如果xQueueReceiveFromISR 引起一個任務解鎖，*pxTaskWoken 將設定為pdTRUE，否則*pxTaskWoken保留不變

Returns: 

pdTRUE ：如果專案成功從佇列接收。

否則為： pdFALSE

24. vQueueAddToRegistry[佇列管理] 

queue.h 

void vQueueAddToRegistry( 

                             xQueueHandle xQueue, 

                             signed portCHAR *pcQueueName, 

                         );

為佇列命名，並加入佇列到登記管理中 

Parameters: 

xQueue	將要新增登記的佇列控制代碼
pcQueueName	為指定的佇列命名。 僅僅是文字串，方便除錯。

佇列登記有兩個特點， 均與核心的相關除錯有關： 

允許文字式名字，使佇列在除錯GUI中方便定義。 

 包含偵錯程式需要的資訊，如：定位每個已經登記的佇列和訊號量。 

佇列的登記沒有目的，除非使用核心相關的除錯。configQUEUE_REGISTRY_SIZE定義了佇列和訊號量的最大數目.僅當使用核心相關的除錯時需要顯示已經登記的訊號量和佇列。 

25. vQueueUnregisterQueue[佇列管理] 

queue.h 

void vQueueUnregisterQueue( 

                             xQueueHandle xQueue, 

                           );

從登記管理中移除佇列。 

Parameters: 

xQueue

從登記管理處中移出的佇列控制代碼

佇列登記有兩個特點， 均與核心的相關除錯有關： 

允許文字式名字，使佇列在除錯GUI中方便定義。 

包含偵錯程式需要的資訊，如：定位每個已經登記的佇列和訊號量。 

佇列的登記沒有目的，除非使用核心相關的除錯。configQUEUE_REGISTRY_SIZE定義了佇列和訊號量的最大數目.僅當使用核心相關的除錯時需要顯示已經登記的訊號量和佇列。 

五、訊號量

26. xSemaphoreCreateCounting[訊號量] 

semphr. h 

xSemaphoreHandle xSemaphoreCreateCounting( unsigned portBASE_TYPE uxMaxCount, unsigned portBASE_TYPE uxInitialCount )

使用已存在的佇列結構來建立計數型訊號量。計數型訊號量有下面兩種典型應用： 

1 事件計數 

在這種應用的情形下，事件處理程式會在每次事件發生時傳送訊號量（增加訊號量計數值），而任務處理程式會在每次處理事件時請求訊號量（減少訊號量計數值）。因此計數值為事件發生與事件處理兩者間的差值，在這種情況下計數值初始化為0是合適的。 

2 資源管理 

在這種應用情形下，計數值指示出可用的資源數量。任務必須首先“請求”訊號量來獲得資源的控制權--減少訊號量計數值。當計數值降為0時表示沒有空閒資源。任務使用完資源後“返還”訊號量--增加訊號量計數值。在這種情況下計數值初始化為與最大的計數值相一致是合適的，這指示出所有的空閒資源。 

引數： 

uxMaxCount	可以達到的最大計數值。當訊號量達到此值後將不能被“返還”。
uxInitialCount	訊號量建立時分配的初始值。

返回： 

已建立的訊號量控制代碼，為xSemaphoreHandle型別，

如果訊號量無法建立則為NULL。 

27. xSemaphoreCreateMutex[訊號量] 

只在FreeRTOS.org V4.5.0以後的版本中可用。 

semphr. h 

xSemaphoreHandle xSemaphoreCreateMutex( void )

使用已存在的佇列結構來建立互斥鎖訊號量的巨集。通過此巨集建立的互斥鎖可以使用xSemaphoreTake()與 xSemaphoreGive()巨集來訪問。不能使用xSemaphoreTakeRecursive()與 xSemaphoreGiveRecursive()巨集。二元訊號量與互斥鎖十分相像，不過兩者間有細微的差別：互斥鎖包含一個優先順序繼承機制，而訊號量沒有。這種差別使得二元訊號量更適合於實現同步（任務之間或任務與中斷之間），互斥鎖更適合於實現簡單的互斥。當有另外一個具有更高優先順序的任務試圖獲取同一個互斥鎖時，已經獲得互斥鎖的任務的優先順序會被提升。已經獲得互斥鎖的任務將繼承試圖獲取同一互斥鎖的任務的優先順序。這意味著互斥鎖必須總是要返還的，否則高優先順序的任務將永遠也不能獲取互斥鎖，而低優先順序的任務將不會放棄優先順序的繼承。 xSemaphoreTake()頁中提供了互斥鎖用於互斥的範例。 

二元訊號量並不需要在得到後立即釋放，因此任務同步可以通過一個任務/中斷持續釋放訊號量而另外一個持續獲得訊號量來實現。xSemaphoreGiveFromISR()頁中有此種方式的實現範例。互斥鎖與二元訊號量均賦值為xSemaphoreHandle型別，並且可以在任何此型別引數的API函式中使用。 

Return: 

已建立的訊號量控制代碼，需要為xSemaphoreHandle型別.

28. xSemaphoreCreateRecursiveMutex[訊號量] 

semphr. h 

xSemaphoreHandle xSemaphoreCreateRecursiveMutex( void )

使用已存在的佇列結構來建立遞迴互斥鎖的巨集。通過此巨集建立的互斥鎖可以使用xSemaphoreTakeRecursive()與 xSemaphoreGiveRecursive()巨集 來訪問。不能使用xSemaphoreTake()與 xSemaphoreGive()巨集。一個遞迴的互斥鎖可以重複地被其所有者“獲取”。在其所有者為每次的成功“獲取”請求呼叫xSemaphoreGiveRecursive()前，此互斥鎖不會再次可用。例如，如果一個任務成功“獲取”同一個互斥鎖5次，則在其“釋放”互斥鎖恰好為5次後，其他任務才可以使用此互斥鎖。這種型別的訊號量使用一個優先順序繼承機制，因此已取得訊號量的任務“必須總是”在不再需要訊號量時立刻“釋放”。互斥型別的訊號量不能在中斷服務程式中使用。可以參考vSemaphoreCreateBinary()來獲得一個二選一執行的實現方式，可以在中斷服務程式中實現純粹的同步（一個任務或中斷總是“釋放”訊號量，而另一個總是“獲取”訊號量）。 

返回： 

已建立的互斥鎖訊號量控制代碼，需要為xSemaphoreHandle型別. 

29. xSemaphoreTake[訊號量] 

semphr. h 

xSemaphoreTake( 

                   xSemaphoreHandle xSemaphore, 

                   portTickType xBlockTime 

               )

用於獲取訊號量的巨集。訊號量必須已經通過呼叫vSemaphoreCreateBinary(), xSemaphoreCreateMutex() 或 xSemaphoreCreateCounting()來建立。這個巨集不能在服務中斷程式中呼叫。如果有必要，可以呼叫xQueueReceiveFromISR() 來在中斷服務程式中獲取訊號量，雖然這並不是一種正規的操作。xSemaphoreTake() 是一個全功能任務間通訊API， xSemaphoreAltTake() 是其等價的替代API 。這兩個版本均需要同樣的引數並返回同樣的值。 

Parameters: 

xSemaphore	將被獲得的訊號量控制代碼，此訊號量必須已經被建立
xBlockTime	等待訊號量可用的時鐘滴答次數，可以使用 portTICK_RATE_MS巨集來轉換為實際的時間 。當為0時可以用於 對訊號量進行輪詢（poll the semaphore）  如果置位“1”，則指定xBlockTime為 portMAX_DELAY會導致任務阻塞時間不確定（不會超時）

返回： 

如果成功獲取訊號量則返回pdTRUE，

如果xBlockTime超時而訊號量還未可用則返回pdFALSE。 

30. xSemaphoreTakeRecursive[訊號量] 

semphr. h 

xSemaphoreTakeRecursive( xSemaphoreHandle xMutex, portTickType xBlockTime )

用於遞迴獲得互斥鎖訊號量的巨集。此互斥鎖必須已經通過呼叫xSemaphoreCreateRecursiveMutex()來建立。 FreeRTOSConfig.h中的configUSE_RECURSIVE_MUTEXES 必須設定為1才可以使用此巨集。此巨集不能用於由xSemaphoreCreateMutex()函式建立的訊號量。一個遞迴型的互斥鎖可以被其所有者重複地“獲取”，一個遞迴的互斥鎖可以重複地被其所有者“獲取”。在其所有者為每次成功的“獲取”請求呼叫 xSemaphoreGiveRecursive()前，此互斥鎖不會再次可用。例如，如果一個任務成功“獲取”同一個互斥鎖5次，則在其“釋放”互斥鎖 恰好為5次後，其他任務才可以使用此互斥鎖。 

引數： 

xMutex	將被獲得的互斥鎖控制代碼，此控制代碼由xSemaphoreCreateRecursiveMutex()返回。
xBlockTime	等待訊號量可用的時鐘滴答次數，可以使用 portTICK_RATE_MS巨集來轉換為實際的時間 。當為0時可以用於 對訊號量進行輪詢（poll the semaphore）。如果任務已經擁有此訊號量則函式將立刻返回，而不管xBlockTime為何值。

返回值： 

如果成功獲取訊號量則返回pdTRUE，

如果xBlockTime超時而訊號量還未可用則返回pdFALSE。

31. xSemaphoreGive[訊號量] 

semphr. h 

xSemaphoreGive( xSemaphoreHandle xSemaphore )

用於釋放訊號量的巨集。這個訊號量必須已經通過呼叫vSemaphoreCreateBinary()， xSemaphoreCreateMutex() 或 xSemaphoreCreateCounting()建立，並且使用sSemaphoreTake()獲取。這個巨集不能在中斷服務程式中使用。參考xSemaphoreGiveFromISR()獲取一個在中斷中使用的替代。這個巨集也不能應用於由xSemaphoreCreateRecursiveMutex()建立的訊號量。xSemaphoreGive()是一個全功能任務間通訊API。xSemaphoreAltGive() 是其等價的替代API。這兩個版本均需要相同的引數，並返回相同的值。 

引數： 

xSemaphore

即將釋放的訊號量的控制代碼，在訊號量建立是返回。

返回值： 

如果訊號量成功釋放返回pdTRUE，如果發生錯誤則返回pdFALSE。訊號量使用的是佇列，因此如果佇列沒有位置用於傳送訊息就會發生一個錯誤——說明開始時沒有正確獲取訊號量。 

32. xSemaphoreGiveRecursive[訊號量]

semphr. h 

xSemaphoreGiveRecursive( xSemaphoreHandle xMutex )

用於遞迴釋放，或‘返還’，互斥鎖訊號量的巨集。這個互斥鎖必須已經通過呼叫xSemaphoreCreateRecursiveMutex()來建立；FreeRTOSConfig.h檔案中的configUSE_RECURSIVE_MUTEXES 必須設定為1來是此巨集可用。 這個巨集不能用與由xSemaphoreCreateMutex().建立的互斥鎖。遞迴的互斥鎖可以被其所有者重複地‘獲取’，在其所有者為每次的成功“獲取”請求呼叫xSemaphoreGiveRecursive()前，此互斥鎖不會再次可用。例如，如果一個任務成功“獲取”同一個互斥鎖5次，則在其“釋放”互斥鎖恰好為5次後，其他任務才可以使用此互斥鎖。 

Parameters: 

xMutex

將被釋放或‘返還’的互斥鎖的控制代碼，由 xSemaphoreCreateRecursiveMutex()返回。

Returns: 

如果訊號量成功釋放則為pdTRUE 

33. xSemaphoreGiveFromISR[訊號量] 

semphr. h 

xSemaphoreGiveFromISR( 

                         xSemaphoreHandle xSemaphore, 

                         portBASE_TYPE *pxHigherPriorityTaskWoken 

                      )

用於釋放一個訊號量的巨集。釋放的訊號量必須已經通過vSemaphoreCreateBinary() 或 xSemaphoreCreateCounting()函式建立。互斥訊號量（通過 xSemaphoreCreateMutex()函式建立）不能使用此巨集。此巨集可以在中斷服務程式中使用。 

引數： 

xSemaphore	將被釋放的訊號量的控制代碼，此控制代碼在訊號量建立時返回。
pxHigherPriorityTaskWoken	如果釋放此訊號量會導致一個比當前任務具有更高優先順序的任務解除阻塞，xSemaphoreGiveFromISR() 函式將設定*pxHigherPriorityTaskWoken為pdTRUE。如果xSemaphoreGiveFromISR() 函式將其置為pdTRUE，則必須在離開中斷前進行上下文切換。

返回： 

如果訊號量成功釋放則返回pdTRUE，

否則返回errQUEUE_FULL。

六、聯合程式 

34. xCoRoutineCreate[聯合程式]

croutine.h 

portBASE_TYPE xCoRoutineCreate(

                                 crCOROUTINE_CODE pxCoRoutineCode,

                                 unsigned portBASE_TYPE uxPriority,

                                 unsigned portBASE_TYPE uxIndex

                               );

建立一個新的聯合程式並且將其增加到聯合程式的就緒列表中 

引數： 

pxCoRoutineCode	聯合程式函式的指標。聯合程式函式需要使用特定的語法——參考聯合程式部分獲取更多資訊。
uxPriority	優先順序，用於與其他聯合程式確定哪個將執行
uxIndex	當不同的聯合程式使用同一個函式來執行時用於相互識別。參考下面的例子以及聯合程式部分獲取更多資訊。

Returns: 

如果聯合程式成功建立並增加到就緒列表中則返回pdPASS，否則返回ProjDefs.h中定義的錯誤程式碼。 

xCoRoutineHandle用於引用聯合程式的型別，聯合程式函式控制代碼可以自動的傳入每一個使用聯合程式的函式。

35. xCoRoutineCreate[聯合程式]

croutine.h 

portBASE_TYPE xCoRoutineCreate(

                                 crCOROUTINE_CODE pxCoRoutineCode,

                                 unsigned portBASE_TYPE uxPriority,

                                 unsigned portBASE_TYPE uxIndex

                               );

建立一個新的聯合程式並且將其增加到聯合程式的就緒列表中 

引數： 

pxCoRoutineCode	聯合程式函式的指標。聯合程式函式需要使用特定的語法——參考聯合程式部分獲取更多資訊。
uxPriority	優先順序，用於與其他聯合程式確定哪個將執行
uxIndex	當不同的聯合程式使用同一個函式來執行時用於相互識別。參考下面的例子以及聯合程式部分獲取更多資訊。

Returns: 

如果聯合程式成功建立並增加到就緒列表中則返回pdPASS，否則返回ProjDefs.h中定義的錯誤程式碼。 

xCoRoutineHandle用於引用聯合程式的型別，聯合程式函式控制代碼可以自動的傳入每一個使用聯合程式的函式。

36. crDELAY[聯合程式] 

croutine.h

void crDELAY( xCoRoutineHandle xHandle, portTickType xTicksToDelay )

crDELAY 是一個巨集，上面原型的資料型別只作為參考。把一個聯合程式延時一個特定的時間。crDELAY只能在聯合程式函式自身內部使用——不能在聯合程式函式呼叫的一個函式內部使用。這是因為聯合函式沒有維護自身的堆疊。 

Parameters: 

xHandle	要延時的聯合程式的控制代碼，這是聯合程式函式的xHandle引數。
xTickToDelay	聯合程式要延時的時間片數。實際的時間相當於configTICK_RATE_HZ (位於 FreeRTOSConfig.h)。可以使用 portTICK_RATE_MS 來轉換為毫秒。

37. crQUEUE_SEND[聯合程式] 

croutine.h

crQUEUE_SEND( 

                  xCoRoutineHandle xHandle, 

                  xQueueHandle pxQueue, 

                  void *pvItemToQueue, 

                  portTickType xTicksToWait, 

                  portBASE_TYPE *pxResult 

             ) 

crQUEUE_SEND是一個巨集，上面原型中的資料型別只用作參考。聯合程式中使用的crQUEUE_SEND() 與 crQUEUE_RECEIVE()巨集等價於任務中的xQueueSend() 與 xQueueReceive()函式。crQUEUE_SEND 與 crQUEUE_RECEIVE 只能被聯合程式使用，而xQueueSend() 與 xQueueReceive()只能被任務使用。注意：聯合程式只能向其他聯合程式傳送資料。聯合程式不能使用佇列來發送向任務傳送資料，反之亦然。crQUEUE_SEND只能在聯合程式函式內部訪問——不能再聯合程式函式呼叫的函式中使用，這是因為聯合函式沒有維護自身的堆疊。 

參考聯合程式部分獲取關於任務與聯合程式或中斷服務程式與聯合程式間傳遞資料的資訊。 

引數： 

xHandle	呼叫的聯合程式的控制代碼，這是聯合程式函式的xHandle引數。
pxQueue	資料將被髮送到的佇列的控制代碼，這是佇列使用 xQueueCreate() API 函式建立時的返回值。
pvItemToQueue	將被髮送到佇列的資料的指標。佇列中每個條目的資料量在佇列建立是已指定，這個數量的位元組資料將從pvItemToQueue中複製到佇列。
xTickToDelay	如果此刻佇列沒有可用空間，此值為聯合程式用於阻塞等待佇列空間可用的時間片數。實際的時間相當於configTICK_RATE_HZ (位於 FreeRTOSConfig.h)。可以使用 portTICK_RATE_MS 來轉換為毫秒。
pxResult	一個指向pxResult變數的指標，如果資料成功傳送到佇列就會被設定為pdPASS，否則設定為 ProjDefs.h中定義的錯誤碼。

38. crQUEUE_RECEIVE[聯合程式] 

croutine.h

void crQUEUE_RECEIVE( 

                     xCoRoutineHandle xHandle, 

                     xQueueHandle pxQueue, 

                     void *pvBuffer, 

                     portTickType xTicksToWait, 

                     portBASE_TYPE *pxResult 

                 )

crQUEUE_RECEIVE 是一個巨集。上面原型的資料型別只用作參考。聯合程式中使用的crQUEUE_SEND() 與 crQUEUE_RECEIVE()巨集等價於任務中的xQueueSend() 與 xQueueReceive()函式。crQUEUE_SEND 與 crQUEUE_RECEIVE 只能被聯合程式使用，而xQueueSend() 與 xQueueReceive()只能被任務使用。注意：聯合程式只能向其他聯合程式傳送資料。聯合程式不能使用佇列來發送向任務傳送資料，反之亦然。crQUEUE_RECEIVE 只能在聯合程式函式內部訪問——不能再聯合程式函式呼叫的函式中使用，這是因為聯合函式沒有維護自身的堆疊。 參考聯合程式部分獲取關於任務與聯合程式或中斷服務程式與聯合程式間傳遞資料的資訊。 

引數： 

xHandle	呼叫的聯合程式的控制代碼，這是聯合程式函式的xHandle引數。
pxQueue	資料將從其中接收的佇列的控制代碼，這是佇列使用 xQueueCreate() API 函式建立時的返回值。
pvBuffer	用於複製接收到的條目的緩衝區，佇列中每個條目的資料量在佇列建立是已指定，這個數量的位元組資料將複製到緩衝區。
xTickToDelay	如果此刻佇列沒有可用空間，此值為聯合程式用於阻塞等待佇列空間可用的時間片數。實際的時間相當於configTICK_RATE_HZ (位於 FreeRTOSConfig.h)。可以使用 portTICK_RATE_MS 來轉換為毫秒。
pxResult	一個指向pxResult變數的指標，如果資料成功傳送到佇列就會被設定為pdPASS，否則設定為 ProjDefs.h中定義的錯誤碼。

39. crQUEUE_SEND_FROM_ISR[聯合程式] 

croutine.h

portBASE_TYPE crQUEUE_SEND_FROM_ISR( 

                                       xQueueHandle pxQueue, 

                                       void *pvItemToQueue, 

                                       portBASE_TYPE xCoRoutinePreviouslyWoken

                                   )

crQUEUE_SEND_FROM_ISR() 是一個巨集。上面原型的資料型別只用作參考。聯合程式中使用的crQUEUE_SEND_FROM_ISR() 與 crQUEUE_RECEIVE_FROM_ISR()巨集等價於任務中的xQueueSendFromISR()與 xQueueReceiveFromISR()函式。crQUEUE_SEND_FROM_ISR() 與 crQUEUE_RECEIVE_FROM_ISR() 只能用於聯合程式與中斷服務程式之間傳遞資料，同樣道理，xQueueSendFromISR() 與 xQueueReceiveFromISR() 只能用於任務與中斷服務程式間傳遞資料。crQUEUE_SEND_FROM_ISR 只能在一個向佇列傳送資料的中斷服務程式中呼叫，並且此佇列在一個聯合程式中使用。參考聯合程式部分獲取關於任務與聯合程式或中斷服務程式與聯合程式間傳遞資料的資訊。 

引數： 

xQueue	將傳送到的佇列的控制代碼。
pvItemToQueue	將被髮送到佇列的條目的指標。佇列中每個條目的資料量在佇列建立是已指定，這個數量的位元組資料將從pvItemToQueue中複製到佇列的儲存空間。
xCoRoutinePreviouslyWoken	包含此項使得一箇中斷服務程式可以在一次中斷中多次向同一個佇列傳送資料。第一次呼叫時必須總是傳入pdFALSE，後面的呼叫時應傳入上一次呼叫返回的值。

Returns: 

如果傳送到佇列使得一個聯合程式喚醒則為pdTRUE。

這用來使中斷服務程式決定是否需要在中斷後進行上下文切換。 

40. crQUEUE_RECEIVE_FROM_ISR[聯合程式]

(注意：官方的文件此處的內容似乎有誤，請參考原始碼)

croutine.h 

portBASE_TYPE crQUEUE_SEND_FROM_ISR( 

                                       xQueueHandle pxQueue, 

                                       void *pvBuffer, 

                                       portBASE_TYPE * pxCoRoutineWoken

                                   ) 

是一個巨集。上面原型的資料型別只用作參考。聯合程式中使用的crQUEUE_SEND_FROM_ISR() 與 crQUEUE_RECEIVE_FROM_ISR()巨集等價於任務中的xQueueSendFromISR()與 xQueueReceiveFromISR()函式。 crQUEUE_SEND_FROM_ISR() 與 crQUEUE_RECEIVE_FROM_ISR() 只能用於聯合程式與中斷服務程式之間傳遞資料，同樣道理，xQueueSendFromISR() 與 xQueueReceiveFromISR() 只能用於任務與中斷服務程式間傳遞資料。 

crQUEUE_RECEIVE_FROM_ISR 只能在一個從佇列接收資料的中斷服務程式中呼叫，並且此佇列在一個聯合程式中使用（一個聯合程式傳送資料到此佇列）。參考聯合程式部分獲取關於任務與聯合程式或中斷服務程式與聯合程式間傳遞資料的資訊。 

Parameters: 

xQueue	The handle to the queue on which the item is to be posted.
pvBuffer	A pointer to a buffer into which the received item will be placed. The size of the items the queue will hold was defined when the queue was created, so this many bytes will be copied from the queue into pvBuffer.
pxCoRoutineWoken	A co-routine may be blocked waiting for space to become available on the queue. If crQUEUE_RECEIVE_FROM_ISR causes such a co-routine to unblock *pxCoRoutineWoken will get set to pdTRUE, otherwise *pxCoRoutineWoken will remain unchanged

Returns: 

pdTRUE an item was successfully received from the queue, otherwise pdFALSE.

41. vCoRoutineSchedule[聯合程式] 

croutine.h

void vCoRoutineSchedule( void );

執行一個聯合程式vCoRoutineSchedule() 與性具有最高優先順序的就緒聯合程式。此聯合程式將執行，直到其阻塞，讓出系統或被任務搶佔。聯合程式是合作式執行的，所以一個聯合程式不會被另一個聯合程式搶佔，但是可以被任務搶佔。如果一個應用程式同時包含任務與聯合程式，則vCoRoutineSchedule應該在空閒任務中呼叫（在一個空閒任務鉤子中）。