1.函數總覽

序號	函數	描述
1	uxTaskPriorityGet()	獲取任務優先級
2	vTaskPrioritySet()	設置任務優先級
3	uxTaskGetNumberOfTasks()	獲取系統中任務的數量
4	uxTaskGetSystemState()	獲取所有任務的狀態信息
5	vTaskGetInfo()	獲取單個任務的狀態信息
6	xTaskGetCurrentTaskHandle()	獲取當前任務的任務句柄
7	xTaskGetHandle()	獲取指定任務的任務句柄
8	uxTaskGetStackHighWaterMark()	獲取任務的任務棧歷史剩余最小值
9	eTaskGetState()	獲取任務狀態
10	vTaskList()	以“表格”形式獲取所有任務的信息
11	vTaskGetRunTimeStats()	獲取任務的運行時間等信息
12	xTaskGetApplicationTaskTag()	獲取任務Tag
13	vTaskSetApplicationTaskTag()	設置任務Tag
14	pcTaskGetName()	獲取任務名
15	xTaskGetSchedulerState()	獲取任務調度器狀態
16	xTaskGetIdleTaskHandle()	獲取空閑任務的任務句柄
17	xTaskGetTickCount()	獲取系統時鐘節拍計數器的值
18	xTaskGetTickCountFromISR()	中斷中獲取系統使用節拍計數器的值
19	GetThreadLocalStoragePointer()	獲取任務的獨有數據記錄數組指針
20	setThreadLocalStoragePointer()	設置任務的獨有數據記錄數組指針

這些API函數主要用于程序調試階段，查看任務運行狀態，以及統計任務時間占比（空
閑任務占比越大，代表應用程序壓力越小）
【本文只闡述一些比較重要的API，其他API可以查閱FreeRTOS官網】

2.重點函數介紹

2.1獲取任務優先級

UBaseType_t  uxTaskPriorityGet(const TaskHandle_t xTask)

• 此函數用于獲取指定任務的任務優先級，使用該函數需將宏 INCLUDE_uxTaskPriorityGet置1
• 形參：xTask，要查找的任務句柄（NULL代表任務自身）
• 返回值：整數，任務優先級數值

2.2.設置任務優先級

void vTaskPrioritySet(TaskHandle_t xTask, UBaseType_t uxNewPriority )

• 此函數用于改變某個任務的任務優先級，使用該函數需將宏 INCLUDE_vTaskPrioritySet置1
• 形參：xTask，任務句柄（NULL代表任務自身）；uxNewPriority，需要設置的任務優先級

2.3.獲取系統中任務數量

UBaseType_t uxTaskGetNumberOfTasks(void)

• 此函數用于獲取系統中任務的任務數量
• 返回值：整型，系統中任務的數量

2.4.獲取所有任務的狀態信息

UBaseType_t  uxTaskGetSystemState(	TaskStatus_t * const 				pxTaskStatusArray,const UBaseType_t 					uxArraySize,configRUN_TIME_COUNTER_TYPE* const 	pulTotalRunTime)
typedef struct xTASK_STATUS
{TaskHandle_t 					xHandle;                /* 任務句柄 */ const char *		 			pcTaskName;             /* 任務名 */ UBaseType_t						xTaskNumber;            /* 任務編號 */ eTaskState e					CurrentState;           /* 任務狀態 */ UBaseType_t 					uxCurrentPriority;      /* 任務優先級 */ UBaseType_t 					uxBasePriority;         /* 任務原始優先級*/ configRUN_TIME_COUNTER_TYPE 	ulRunTimeCounter; 		/* 任務運行時間*/StackType_t * 					pxStackBase;            /* 任務棧基地址 */ configSTACK_DEPTH_TYPE 			usStackHighWaterMark;  	/* 任務棧歷史剩余最小值 */ 
} TaskStatus_t;

• 此函數用于獲取系統中所有任務的任務狀態信息，使用該函數需將宏configUSE_TRACE_FACILITY置1
• 形參：xTaskStatusArray，指向TaskStatus_t 結構體數組首地址（一般要自行分配）
• 形參：uxArraySize，接收信息的數組大小（一般為任務數量）
• 形參：pulTotalRunTime，系統總運行時間，為NULL 則省略總運行時間值（一般為NULL）
• 返回值：整型，獲取信息的任務數量

2.5.獲取單個任務的狀態信息

void vTaskGetInfo(	TaskHandle_t 	xTask, TaskStatus_t* 	pxTaskStatus, 	BaseType_t 		xGetFreeStackSpace,eTaskState 		eState)
typedef enum
{   eRunning = 0,	/* 運行態 */ eReady			/* 就緒態 */ eBlocked, 		/* 阻塞態 */ eSuspended, 	/* 掛起態 */ eDeleted, 		/* 任務被刪除 */ eInvalid		/* 無效 */ 
} eTaskState;

• 此函數用于獲取指定的單個任務的狀態信息，使用該函數需將宏configUSE_TRACE_FACILITY置1
• 形參：xTask，指定獲取信息的任務的句柄
• 形參：pxTaskStatus，接收任務信息的變量
• 形參：xGetFreeStackSpace，任務棧歷史剩余最小值（當為pdFALSE跳過這個步驟，當為pdTRUE檢查歷史剩余最小堆棧）
• 形參：eState，任務狀態，可直接賦值，如想獲取代入“eInvalid”

2.6.獲取當前任務的任務句柄

TaskHandle_t xTaskGetCurrentTaskHandle(void) 

• 此函數用于獲取當前任務的任務句柄，使用該函數需將宏 INCLUDE_xTaskGetCurrentTaskHandle置1
• 返回值：TaskHandle_t ，當前任務的任務句柄

2.7.獲取指定任務的任務句柄

TaskHandle_t xTaskGetHandle(const char* pcNameToQuery); 

• 此函數用于通過任務名獲取任務句柄，使用該函數需將宏 INCLUDE_xTaskGetHandle置1
• 形參：pcNameToQuery，任務名
• 返回值：TaskHandle，任務句柄

2.8.獲取任務的任務棧歷史剩余最小值

UBaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask)

• 此函數用于獲取指定任務的任務棧歷史最小剩余堆棧，使用該函數需將宏 INCLUDE_uxTaskGetStackHighWaterMark置1
• 形參：xTask，任務句柄
• 返回值：UBaseType_t，任務棧的歷史剩余最小值

2.9.獲取任務狀態

eTaskState    eTaskGetState(TaskHandle_t xTask)
typedef enum
{   eRunning = 0,	/* 運行態 */ eReady			/* 就緒態 */ eBlocked, 		/* 阻塞態 */ eSuspended, 	/* 掛起態 */ eDeleted, 		/* 任務被刪除 */ eInvalid		/* 無效 */ 
} eTaskState;

• 此函數用于查詢某個任務的運行狀態，使用此函數需將宏 INCLUDE_eTaskGetState置1
• 形參：xTask，待獲取狀態任務的任務句柄
• 返回值：eTaskState，任務狀態

2.10.以“表格”形式獲取所有任務的信息（類似于2.4獲取所有任務的狀態信息）

void vTaskList(char* pcWriteBuffer)

• 此函數用于以“表格”的形式獲取系統中任務的信息，使用此函數需將宏 configUSE_TRACE_FACILITY、configUSE_STATS_FORMATTING_FUNCTIONS 置1
• 形參：pcWriteBuffer，接收任務信息的緩存指針

Name： 創建任務的時候給任務分配的名字。
State： 任務的壯態信息，X是運行態，B是阻塞態， R是就緒態，S是掛起態， D是刪除態
Priority ：任務優先級。
Stack ： 任務堆棧的“高水位線”，就是堆棧歷史最小剩余大小。
Num ： 任務編號，這個編號是唯一的，當多個任務使用同一個任務名的時候可以通過此編號來做區分。

2.11.獲取任務的運行時間等信息

Void vTaskGetRunTimeStats(char * pcWriteBuffer)

• 此函數用于統計任務的運行時間信息，使用此函數需將宏 configGENERATE_RUN_TIME_STATS，configUSE_STATS_FORMATTING_FUNCTIONS 置1
• 形參：pcWriteBuffer，接收任務運行時間信息的緩存指針

Task：任務名稱
Abs Time：任務實際運行的總時間（絕對時間）
% Time：占總處理時間的百分比

時間統計API函數使用流程：

1. 將宏 configGENERATE_RUN_TIME_STATS 置1
2. 將宏 configUSE_STATS_FORMATTING_FUNCTIONS 置1
3. 當將此宏 configGENERATE_RUN_TIME_STATS 置1之后，還需要實現2個宏定義：
   ① portCONFIGURE_TIMER_FOR_RUNTIME_STATE() ：用于初始化用于配置任務運行時間統計的時基定時器（該函數一般調用時基定時器的初始化，配置時間精度，這個時基定時器的計時精度需高于系統時鐘節拍精度的10至100倍！）
   ② portGET_RUN_TIME_COUNTER_VALUE()：用于獲取該功能時基硬件定時器計數的計數值（一般在時基函數初始化時置0，在定時器中斷中自增）