ESP32 SDK开发环境搭建 安信可 esp32 api

文章目录

• 概述

• 任务API

• 头文件

• freertos/include/freertos/task.h

• 函数

• xTaskCreatePinnedToCore
• xTaskCreate
• xTaskCreateStaticPinnedToCore
• xTaskCreateStatic
• vTaskAllocateMPURegions
• vTaskDelete
• vTaskDelay
• vTaskDelayUntil
• xTaskAbortDelay
• uxTaskPriorityGet
• uxTaskPriorityGetFromISR
• eTaskGetState
• vTaskGetInfo
• vTaskPrioritySet
• vTaskSuspend
• vTaskResume
• xTaskResumeFromISR
• vTaskSuspendAll
• xTaskResumeAll
• xTaskGetTickCount
• xTaskGetTickCountFromISR
• uxTaskGetNumberOfTasks
• pcTaskGetName
• xTaskGetHandle
• uxTaskGetStackHighWaterMark
• uxTaskGetStackHighWaterMark2
• pxTaskGetStackStart
• vTaskSetApplicationTaskTag
• xTaskGetApplicationTaskTag
• xTaskGetApplicationTaskTagFromISR
• vTaskSetThreadLocalStoragePointer
• pvTaskGetThreadLocalStoragePointer
• vTaskSetThreadLocalStoragePointerAndDelCallback
• xTaskCallApplicationTaskHook
• xTaskGetIdleTaskHandle
• uxTaskGetSystemState
• vTaskList
• vTaskGetRunTimeStats
• ulTaskGetIdleRunTimeCounter
• xTaskGenericNotify
• xTaskGenericNotifyFromISR
• xTaskNotifyWait
• vTaskNotifyGiveFromISR
• ulTaskNotifyTake
• xTaskNotifyStateClear

• 宏命令
• 类型定义
• 枚举

• eTaskState
• eNotifyAction
• eSleepModeStatus

---

概述

本章节包含FreeRTOS 任务的类型、函数和宏的文档。

---

注解：ESP-IDFFreeRTOS是基于FreeRTOSv10.2.0的Xtensa端口构建的

---

有关特定于ESP-IDF的FreeRTOS功能的更多信息，看 ESP-IDF FreeRTOS SMP Changes 和 ESP-IDF FreeRTOS Additions

任务API

头文件

freertos/include/freertos/task.h

---

函数

xTaskCreatePinnedToCore

BaseType_t xTaskCreatePinnedToCore(TaskFunction_t pvTaskCode, 
                                    const char *const pcName, 
                                    const uint32_t usStackDepth, 
                                    void *const pvParameters, 
                                    UBaseType_t uxPriority, 
                                    TaskHandle_t *constpvCreatedTask, 
                                    const BaseType_t xCoreID)
    创建一个具有指定的关联关系的新任务。
    此函数类似于xTaskCreate，但允许在SMP系统中设置任务关联。
    Return pdPASS 如果任务成功创建并添加到就绪列表，否则在文件projdefs.h中定义错误代码
    Parameters
        * pvTaskCode: 指向任务输入函数的指针。任务必须被实现为永不Return（如：死循环），或者应该使用vtTaskDelete函数终止。
        * pcName：该任务的描述性名称。这主要用于方便调试。通过设置 **MAX_TASK_NAME_LEN** 定义最大长度-默认值为16。
        * usStackDepth：指定为字节数的任务堆栈的大小。请注意，这不同于vanilla FreeRTOS。
        * pvParameters：将用作所创建的任务的参数的指针。
        * uxPriority：任务运行的优先级。包含MPU支持的系统可以通过设置优先级参数的位portPRIVILEGE_BIT来选择在特权（系统）模式下创建任务。
                      例如，要在优先级2处创建特权任务，应将uxPriority参数设置为(2|portPRIVILEGE_BIT)。
        * pvCreatedTask：用于传递回可引用所创建任务的句柄。
        * xCoreID：如果值为tskNO_AFFINITY，则创建的任务不会固定到任何CPU，调度程序可以在任何可用的核心上运行。
                   值0或1表示任务应固定到的CPU的索引编号。
                   指定大于（portNUM_PROCESSORS-1）的值将导致函数失败。

---

xTaskCreate

static BaseType_t xTaskCreate(TaskFunction_t pvTaskCode, 
                              const char *const pcName, 
                              const uint32_t usStackDepth, 
                              void *const pvParameters, 
                              UBaseType_t uxPriority, 
                              TaskHandle_t *const pvCreatedTask)
    创建一个新任务，并将其添加到准备运行的任务列表中。
    在内部，在FreeRTOS实现中，任务使用两个内存块。第一个块用于保存任务的数据结构。第二个块被任务用作其堆栈。如果使用xTaskCreate()创建任务，则在xTaskCreate()函数中自动动态分配两个内存块。 (see http://www.freertos.org/a00111.html).如果使用xTaskCreateStatic()创建任务，则应用程序编写器必须提供所需的内存。因此，xTaskCreateStatic()允许在不使用任何动态内存分配的情况下创建任务。
    有关不使用任何动态内存分配的版本，请参见xTaskCreateStatic()。
    xTaskCreate()只能用于创建能够无限制地访问整个微控制器内存映射的任务。包含MPU支持的系统也可以使用xTaskCreateRestricted()创建MPU受限的任务。

    Return pdPASS 如果任务成功创建并添加到就绪列表，否则在文件projdefs.h中定义错误代码
    Note 如果程序使用线程局部变量（用“__thread”关键字指定的局部变量），则将在任务的堆栈上为它们分配存储空间。
    Parameters
        * pvTaskCode：指向任务输入函数的指针。任务必须被实现为永不Return（如：死循环），或者应该使用vtTaskDelete函数终止。
        * pcName：该任务的描述性名称。这主要用于方便调试。通过设置 **MAX_TASK_NAME_LEN** 定义最大长度-默认值为16。
        * usStackDepth：指定为字节数的任务堆栈的大小。请注意，这不同于vanilla FreeRTOS。
        * pvParameters：将用作所创建的任务的参数的指针。
        * uxPriority：任务运行的优先级。包含MPU支持的系统可以通过设置优先级参数的位portPRIVILEGE_BIT来选择在特权（系统）模式下创建任务。
                      例如，要在优先级2处创建特权任务，应将uxPriority参数设置为(2|portPRIVILEGE_BIT)。
        * pvCreatedTask：用于传递回可引用所创建任务的句柄。

示例用法：
    // 要创建的任务
    void vTaskCode( void * pvParameters )
    {
        for( ;; )
        { 
            //任务代码就在这里了。
        }
    }

    // 创建任务的函数。
    void vOtherFunction( void )
    {
        static uint8_t ucParameterToPass;
        TaskHandle_t xHandle = NULL;
        // 创建任务，保存句柄。
        // 注意被传递的参数ucParameterToPass，在任务的生命周期内必须存在，所以这里声明static。
        // 如果它只是一个自动堆栈变量，那么当新任务试图访问它时，它可能已经不复存在了，或者至少已经被损坏了。
        xTaskCreate( vTaskCode, 
                     "NAME", 
                     STACK_SIZE, 
                     &ucParameterToPass, 
                     tskIDLE_PRIORITY, 
                     &xHandle );

        configASSERT( xHandle );

        // 使用该句柄可以删除该任务。
        if( xHandle != NULL )
        {
            vTaskDelete( xHandle );
        } 
    }

---

xTaskCreateStaticPinnedToCore

TaskHandle_t xTaskCreateStaticPinnedToCore(TaskFunction_t pvTaskCode, 
											const char*const pcName, 
											const uint32_t ulStackDepth, 
											void *const pvParameters, 
											UBaseType_t uxPriority, 
											StackType_t *const pxStackBuffer, 
											StaticTask_t *const pxTaskBuffer,										
											const BaseType_t xCoreID)
	创建一个具有指定的关联关系的新任务。
	此函数类似于xTaskCreateStatic，但允许在SMP系统中指定任务关联。
	Return 如果pxStackBuffer或pxTaskBuffer都不为空，则将创建任务并返回pdPASS。
		   如果pxStackBuffer或pxTaskBuffer为NULL，则将不会创建该任务，并返回errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY。
	Parameters
		* pvTaskCode：指向任务输入函数的指针。任务必须被实现为永不Return（如：死循环），或者应该使用vtTaskDelete函数终止。
		* pcName：该任务的描述性名称。这主要用于方便调试。字符串的最大长度由FreeRTOSConfig.h.中的configMAX_TASK_NAME_LEN定义。
		* ulStackDepth：指定为字节数的任务堆栈的大小。请注意，这不同于vanilla FreeRTOS。
		* pvParameters：将用作所创建的任务的参数的指针。
        * uxPriority：任务运行的优先级。包含MPU支持的系统可以通过设置优先级参数的位portPRIVILEGE_BIT来选择在特权（系统）模式下创建任务。
                      例如，要在优先级2处创建特权任务，应将uxPriority参数设置为(2|portPRIVILEGE_BIT)。
        * pvCreatedTask：用于传递回可引用所创建任务的句柄。

---

xTaskCreateStatic

static TaskHandle_t xTaskCreateStatic(TaskFunction_t pvTaskCode, 
									  const char *const pcName, 
									  const uint32_t ulStackDepth, 
									  void *const pvParameters, 
									  UBaseType_t uxPriority, 
									  StackType_t*const pxStackBuffer, 
									  StaticTask_t *const pxTaskBuffer)	
									  								  
	创建一个新任务，并将其添加到准备运行的任务列表中。
	在内部，在FreeRTOS实现中，任务使用两个内存块。第一个块用于保存任务的数据结构。第二个块被任务用作其堆栈。
	如果使用xTaskCreate()创建任务，则在xTaskCreate()函数中自动动态分配两个内存块。
	如果使用xTaskCreateStatic()创建任务，则应用程序编写器必须提供所需的内存。
	因此，xTaskCreateStatic()允许在不使用任何动态内存分配的情况下创建任务。

	Return 如果pxStackBuffer或pxTaskBuffer都不为空，则将创建任务并返回pdPASS。
		   如果pxStackBuffer或pxTaskBuffer为NULL，则将不会创建该任务，并返回errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY。
    Note   如果程序使用线程局部变量（用“__thread”关键字指定的局部变量），则将在任务的堆栈上为它们分配存储空间。
	Parameters
		* pvTaskCode：指向任务输入函数的指针。任务必须被实现为永不Return（如：死循环），或者应该使用vtTaskDelete函数终止。
		* pcName：该任务的描述性名称。这主要用于方便调试。字符串的最大长度由FreeRTOSConfig.h.中的config MAX_TASK_NAME_LEN定义。
		* ulStackDepth：指定为字节数的任务堆栈的大小。请注意，这不同于vanilla FreeRTOS。
		* pvParameters：将用作所创建的任务的参数的指针。
        * uxPriority：任务运行的优先级。包含MPU支持的系统可以通过设置优先级参数的位portPRIVILEGE_BIT来选择在特权（系统）模式下创建任务。
                      例如，要在优先级2处创建特权任务，应将uxPriority参数设置为(2|portPRIVILEGE_BIT)。
		* pxStackBuffer：必须指向至少具有ulStackDepth索引的StackType_t数组——然后该数组将用作任务的堆栈，从而无需动态分配该堆栈。
        * pxTaskBuffer：必须指向StaticTask_t类型的变量，然后使用该变量保存任务的数据结构，从而无需动态分配内存。
    
	示例用法：
	//调整所创建的任务将用作其堆栈的缓冲区的大小。
	//注意：这是堆栈将保留的字节数，而不是在vanilla FreeRTOS中的单词的数量。
	#define STACK_SIZE 200
	
	//将保存所创建任务的TCB的结构。
	StaticTask_t xTaskBuffer;
	
	//正在创建的任务将用作其堆栈的缓冲区。
	//注意，这是一个包含StackType_t变量的数组
	//StackType_t的大小取决于RTOS端口。
	StackType_t xStack[ STACK_SIZE ];

	//实现正在创建的任务的函数。
	void vTaskCode( void * pvParameters )
	{ 
		// 参数值应为1，因为在呼叫xTaskCreateStatic()时的pv参数值中传递了1。
		configASSERT( ( uint32_t ) pvParameters == 1UL );
		for( ;; )
		{ 
			// 任务代码就在这里了。
		} 
	}
	
	//创建任务的函数。
	void vOtherFunction( void )
	{
		TaskHandle_t xHandle = NULL;
		// 创建该任务，而不使用任何动态内存分配。
		xHandle = xTaskCreateStatic(
					vTaskCode, // 实现该任务的函数。
					"NAME", // 该任务的文本名称。
					STACK_SIZE, // 堆栈为字节大小，单位为字节，而不是单词。
					( void * ) 1, // 传递到任务中的参数。
					tskIDLE_PRIORITY,// 创建任务的优先级。
					xStack, // 要用作任务的堆栈的数组。
					&xTaskBuffer ); // 用来保存任务的数据结构的变量。
		// puxStack缓冲区和pxTaskBuffer不是NULL，因此将已创建任务，而xHandle将是任务的句柄。
		// 使用该句柄可以挂起该任务。
		vTaskSuspend( xHandle );
	}

---

vTaskAllocateMPURegions

void vTaskAllocateMPURegions(TaskHandle_t xTask, 
							 const MemoryRegion_t *const pxRegions)

---

vTaskDelete

void vTaskDelete(TaskHandle_t xTaskToDelete)
	
	从RTOS实时内核管理中删除任务。要删除的任务将从所有已就绪、阻止、挂起和事件列表中删除。
	INCLUDE_vTaskDelete必须定义为1，这样此函数才可用。有关详细信息，请参见配置部分。
	注意：空闲任务负责从已删除的任务中释放内核分配的内存。因此重要的是，如果您的应用程序调用了vTaskDelete()，空闲的任务并不缺少微控制器的处理时间。
任务代码分配的内存不会自动释放，应该在删除任务之前释放。
	有关使用vTaskdelete()的示例代码，请参见演示应用程序文件dere.c。
	
	Parameters
		* xTaskToDelete：要删除的任务的句柄。传递NULL将导致删除调用任务。	

	示例用法：
	void vOtherFunction( void )
	{
		TaskHandle_t xHandle;
		// 创建任务，存储句柄。
		xTaskCreate( vTaskCode, 
					"NAME", 
					STACK_SIZE, 
					NULL, 
					tskIDLE_PRIORITY, 
					&xHandle );
		// 使用该句柄可以删除该任务。
		vTaskDelete( xHandle );
	}

---

vTaskDelay

void vTaskDelay(const TickType_t xTicksToDelay)

	延迟给定的滴答数的任务。任务剩下被阻止的实际时间取决于滴答率。
	常数portTICK_PERIOD_MS可用于实时计算从刻答率-与一个滴答周期的分辨率。
	INCLUDE_vTaskDelay必须定义为1，这样此函数才可用。有关详细信息，请参见配置部分。
	vTaskDelay()指定任务希望相对于调用vTaskDelay()的时间解除阻止的时间。
	例如，指定100ticks的堵塞周期将导致任务在调用vTaskDelay()之后100ticks取消阻塞。
	因此，vTaskDelay()不能作为通过代码所采取的路径来控制周期任务频率的好方法，以及其他任务和中断活动，将影响调用vTaskDelay()的频率以及下一次执行任务的时间。
	vTaskDelayUntil()为旨在方便固定频率的替代API函数执行。它通过指定调用任务应取消阻止阻塞的绝对时间（而不是相对时间）来实现这一点。
	
	Parameters
		* 在时间周期里，任务阻塞的时间量。
	
	示例用法：
	void vTaskFunction( void * pvParameters )
	{
		// 阻塞500ms.
		const TickType_t xDelay = 500 / portTICK_PERIOD_MS;
		for( ;; )
		{ 
			// 每500ms切换LED，每个切换之间阻塞。
			vToggleLED();
			vTaskDelay( xDelay );
		} 
	}

---

vTaskDelayUntil

void vTaskDelayUntil(TickType_t *const pxPreviousWakeTime, 
					 const TickType_t xTimeIncrement)
	
	将任务延迟到指定的时间为止。此功能可用于定期任务，以确保执行频率不变。
	INCLUDE_vTaskDelayUntil必须定义为1，这样此函数才可用。有关详细信息，请参见配置部分。
	此函数与vTaskDelay()在一个重要方面有所不同：
		vTaskDelay()将导致一个任务从调用vTaskDelay()时开始阻止指定的ticks数。
		因此很难使用vTaskDelay()本身生成一个固定的执行频率作为任务开始执行之间的时间，
	任务调用vTaskDelay()可能不固定[任务可能采取不同的路径虽然调用之间的代码，或可能被中断或抢占每次执行不同的次数]。
		而vTaskDelay()指定了相对于函数被调用的时间的唤醒时间，vTaskDelayUntil()指定要取消阻止的绝对（确切）时间。
	常数portTICK_PERIOD_MS可用于实时计算从刻答率-与一个滴答周期的分辨率。

	Parameters
		* pxPreviousWakeTime：指向保存上次解除任务的变量的指针。变量必须在首次使用之前使用当前时间初始化（见以下示例）。
		* 					  接下来，该变量将在vTaskDelayUntil()中自动更新。
		* xTimeIncrement：周期周期。任务将在时间+时间增量时解除阻塞。使用相同的xTimeIncrement调用vTaskDelayUntil，将导致任务以固定的周期执行。

	示例用法：
	// 每10个ticks执行一个动作。
	void vTaskFunction( void * pvParameters )
	{
		TickType_t xLastWakeTime;
		const TickType_t xFrequency = 10; 
		// 使用当前时间初始化xLastWakeTime变量。
		xLastWakeTime = xTaskGetTickCount ();
		for( ;; )
		{ 
			// 请等待下一个周期。
			vTaskDelayUntil( &xLastWakeTime, xFrequency );
			// 请在此处执行相应的操作。
		} 
	}

---

xTaskAbortDelay

BaseType_t xTaskAbortDelay(TaskHandle_t xTask)

---

uxTaskPriorityGet

UBaseType_t uxTaskPriorityGet(const TaskHandle_t xTask)

	获得任何任务的优先级。
	INCLUDE_uxTaskPriorityGet必须定义为1，这样此函数才可用。有关详细信息，请参见配置部分。

	Return xTask的优先级。
	Parameters
		- xTask：要查询的任务的句柄。传递NULL句柄会导致返回的调用任务的优先级。
	
	示例用法：
	void vAFunction( void )
	{
		TaskHandle_t xHandle;
		// 创建一个任务，并存储该句柄。
		xTaskCreate( vTaskCode, 
					"NAME", 
					STACK_SIZE, 
					NULL, 
					tskIDLE_PRIORITY, 
					&xHandle);
					
		// ...
		
		// 使用该句柄可获取所创建任务的优先级。
		// 它是用tskIDLE_PRIORITY创建的，但可能已经改变了它本身。
		if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
		{
			// 这个任务已经改变了它的优先级。
		}
		
		// ...
		
		// 我们的优先级是否高于已创建的任务？
		if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
		{
			// 我们的优先级（使用NULL句柄获得）更高。
		} 
	}

---

uxTaskPriorityGetFromISR

UBaseType_t uxTaskPriorityGetFromISR(const TaskHandle_t xTask)

	可以从ISR中使用的 uxTaskPriorityGet()的一个版本。

---

eTaskGetState

eTaskState eTaskGetState(TaskHandle_t xTask)

	获取任何任务的状态。
	状态由eTaskState枚举的类型进行编码。
	INCLUDE_eTaskGetState必须定义为1，这样此函数才可用。有关详细信息，请参见配置部分。
	
	Return：调用该函数时的xTask的状态。注意，任务的状态可能会在被调用的函数和被调用任务测试的函数返回值之间发生变化。
	Parameters：
		- 要查询的任务的句柄。

---

vTaskGetInfo

void vTaskGetInfo(TaskHandle_t xTask, 
				  TaskStatus_t *pxTaskStatus, 
				  BaseType_t xGetFreeStackSpace,
				  eTaskState eState)
				  
	使用有关任务的信息 填充 TaskStatus_t结构。
	configUSE_TRACE_FACILITY必须定义为1，这样此函数才可用。有关详细信息，请参见配置部分。
	
	Parameters：
		* xTask：要查询的任务的句柄。如果xTask为NULL，则将返回有关调用任务的信息。
		* pxTaskStatus：指向TaskStatus_t结构的指针，将填充使用xTask参数传递的句柄引用的任务的信息。
		* xGetFreeStackSpace：TaskStatus_t结构包含一个用来报告被查询的任务的堆栈高水位标记的成员。
							  计算堆叠高水位标记需要相对较长的时间，并且会使系统暂时失去响应——因此提供了xGetFreeStackSpace参数，以允许跳过高水位标记检查。
							  只有当xGetFreeStackSpace未设置为pdFALSE时，高水印值才会写入TaskStatus_t结构；
		* eState：TaskStatus_t结构包含一个用于报告所查询任务的状态的成员。
				  获得任务状态不如简单的分配那么快，因此提供了eState参数，以允许从TaskStatus_t结构中省略状态信息。
				  要获取状态信息，然后将eState设置为 eInvalid，否则在eState中传递的值将被报告为TaskStatus_t结构中的任务状态。

	 示例用法：
	 void vAFunction( void )
	{
		TaskHandle_t xHandle;
		TaskStatus_t xTaskDetails;
		// 从任务的名称中获取该任务的句柄。
		xHandle = xTaskGetHandle( "Task_Name" );
		// 检查句柄是否为空。
		configASSERT( xHandle );
		// 使用该句柄可获取有关该任务的进一步信息。
		vTaskGetInfo( xHandle,
					  &xTaskDetails,
				      pdTRUE, // 在xTaskDetails中包括高水位标记。
					  eInvalid ); // 在xTaskDetails中包含任务状态。
	}

---

vTaskPrioritySet

void vTaskPrioritySet(TaskHandle_t xTask, 
					  UBaseType_t uxNewPriority)
	
	设置任何任务的优先级。
	INCLUDE_vTaskPrioritySet必须定义为1，这样此函数才可用。有关详细信息，请参见配置部分。
	如果设置的优先级高于当前执行的任务，则在函数返回之前发生上下文切换。

	Parameters
		* xTask：对要为其设置优先级的任务的句柄。传递NULL句柄会导致正在设置的调用任务的优先级。
		* uxNewPriority：将设置任务的优先级。

	示例用法：
	void vAFunction( void )
	{
		TaskHandle_t xHandle;
		// 创建一个任务，并存储该句柄。
		xTaskCreate( vTaskCode, 
					 "NAME", 
					 STACK_SIZE, 
					 NULL, 
					 tskIDLE_PRIORITY, 
					 &xHandle);
					 
		// ... 

		// 使用该句柄可以提高所创建的任务的优先级。
		vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 );
		
		// ... 

		// 使用空句柄将我们的优先级提升到相同的值。
		vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );
	}

---

vTaskSuspend

void vTaskSuspend(TaskHandle_t xTaskToSuspend)

	INCLUDE_vTaskSuspend必须定义为1，这样此函数才可用。有关详细信息，请参见配置部分。
	挂起任何任务。当挂起时，任务的任何微控制器处理时间都永远不会得到，无论其优先级是什么。
	对vTaskSuspend的调用不是累积的。例如：在同一任务上调用两次vTaskSuspend()仍然只需要调用一次vTaskResume()即可准备好挂起的任务。

	Parameters
		* xTaskToSuspend：正在挂起任务的句柄。传递NULL句柄将导致调用任务挂起。

	示例用法：
	void vAFunction( void )
	{
		TaskHandle_t xHandle;
		// 创建一个任务，并存储该句柄。
		xTaskCreate( vTaskCode, 
					 "NAME", 
					 STACK_SIZE, 
					 NULL, 
					 tskIDLE_PRIORITY, 
					 &xHandle);
					 
		// ... 
		
		// 使用该句柄可以挂起已创建的任务。
		vTaskSuspend( xHandle );
		
		// ... 
		
		// 已创建的任务将不会在此期间运行，除非另一个任务调用vtaskResume(xHandle)。
		
		//... 

		// 挂起自己。
		vTaskSuspend( NULL );
		
		// 除非另一个任务调用以我们的句柄作为参数的vtaskResume，否则我们无法到达这里。
	}

---

vTaskResume

void vTaskResume(TaskHandle_t xTaskToResume)

	恢复已挂起的任务。
	INCLUDE_vTaskSuspend必须定义为1，这样此函数才可用。有关详细信息，请参见配置部分。
	被一个或多个vTaskSuspend()调用挂起的任务将通过对vTaskResume()的调用再次运行。
	
	Parameters
		* xTaskToResume：对正在准备好的任务的句柄。

	示例用法：
	void vAFunction( void )
	{
		TaskHandle_t xHandle;
		// 创建一个任务，并存储该句柄。
		xTaskCreate( vTaskCode, 
					 "NAME", 
					 STACK_SIZE, 
					 NULL, 
					 tskIDLE_PRIORITY, 
					 &xHandle);
					 
		// ... 
		
		// 使用该句柄可以挂起已创建的任务。
		vTaskSuspend( xHandle );
		
		// ... 

		// 已创建的任务将不会在此期间运行，除非另一个任务调用vtaskResume(xHandle)。 

		//... 
	
		// 我们自己恢复已挂起的任务。
		vTaskResume( xHandle );

		// 所创建的任务将再次根据其在系统内的优先级获得微控制器的处理时间。
	}

---

xTaskResumeFromISR

BaseType_t xTaskResumeFromISR(TaskHandle_t xTaskToResume)

	可以在ISR中调用的vTaskResume()的一种实现。
	INCLUDE_xTaskResumeFromISR必须定义为1，这样此函数才可用。有关详细信息，请参见配置部分。
	已被一个或多个对vTaskSuspend()的调用暂停的任务将通过一次对xTaskResumeFromISR()的调用再次运行。
	如果中断有可能在任务挂起之前到达，那么xTaskResumeFromISR()不应用于将任务与中断同步——因为这可能会导致中断被错过。
	使用信号量作为同步机制将避免这种情况的发生。

	Return	pdTRUE，如果恢复任务应该导致上下文切换，否则是pdFALSE。ISR使用此功能来确定在ISR之后是否需要上下文切换。
	Parameters
		* xTaskToResume：对正在准备好的任务的句柄。

---

vTaskSuspendAll

void vTaskSuspendAll(void)
	
	挂起调度程序，而不禁用中断。
	当调度程序被挂起时，将不会发生上下文切换。
	调用vTaskSuspendAll()后，调用任务将继续执行，不会有被交换的风险，直到调用xTaskResumeAll()为止。
	有可能导致上下文切换的API函数（例如，vTaskDelayUntil()、xQueueSend()等）。在调度程序挂起时不能调用。

	示例用法：

	void vTask1( void * pvParameters )
	{
		for( ;; )
		{ 
			// 任务代码就在这里。 

			// ... 

			// 在某个时候，任务希望执行长操作，在此期间它不希望交换。
			// 它不能使用taskENTER_CRITICAL()/taskEXIT_CRITICAL()，因为操作的长度可能会导致错过中断——包括ticks。
			
			//防止实时内核交换任务。
			vTaskSuspendAll ();
			
			// 请在此处执行该操作。
			// 没有必要使用关键的部分，因为我们有所有的微控制器处理时间。
			// 在此期间，中断仍将运行，内核滴答计数将保持不变。

			//...

			//该操作已完成。重新启动内核。
			xTaskResumeAll ();
		}
	}

---

xTaskResumeAll

BaseType_t xTaskResumeAll(void)

	在调用vTaskSuspendAll()挂起后恢复调度程序。
	xTaskResumeAll()只恢复调度程序。它不会取消以前通过调用vTaskSuspend()而挂起的任务。
	
	Return 如果恢复调度程序导致上下文切换，则返回pdTRUE，否则返回pdFALSE。

	示例用法：
	void vTask1( void * pvParameters )
	{
		for( ;; )
		{
			// 任务代码就在这里。
			
			// ...
			
			// 在某个时候，任务希望执行长操作，在此期间它不希望交换。
			// 它不能使用taskENTER_CRITICAL()/taskEXIT_CRITICAL()，因为操作的长度可能会导致错过中断——包括ticks。
			
			//防止实时内核交换任务。
			vTaskSuspendAll ();
			
			// 请在此处执行该操作。
			// 没有必要使用关键的部分，因为我们有所有的微控制器处理时间。
			// 在此期间，中断仍将运行，内核滴答计数将保持不变。
		
			// ...
			
			// 该操作已完成。重新启动内核。
			// 我们想强制上下文切换——但是如果恢复调度程序已经导致上下文切换，就没有意义。
			if( !xTaskResumeAll () )
			{
				taskYIELD ();
			} 
		}
	}

---

xTaskGetTickCount

TickType_t xTaskGetTickCount(void)

	获取滴答数。
	Return 自调用vTaskStartScheduler以来的滴答数。

---

xTaskGetTickCountFromISR

TickType_t xTaskGetTickCountFromISR(void)

	从ISR获得滴答数。
	这是xTaskGetTickCount()的一个版本，可以安全地从ISR中调用——只要TickType_t是正在使用的微控制器的自然字大小或中断嵌套不被支持或不被使用。

	Return 自调用vTaskStartScheduler以来的滴答数。

---

uxTaskGetNumberOfTasks

UBaseType_t uxTaskGetNumberOfTasks(void)

	获取当前的任务数。
	Return 实时内核当前正在管理的任务数。
		   这包括所有已准备就绪、已阻止和已挂起的任务。
		   已删除但尚未被空闲任务释放的任务也将包含在计数中。

---

pcTaskGetName

char *pcTaskGetName(TaskHandle_t xTaskToQuery)

	获取任务名称。
	Return 句柄xTaskToQuery所引用的任务的名称。
		   任务可以通过传递自己的句柄或将xTaskToQuery设置为NULL来查询自己的名称。

---

xTaskGetHandle

TaskHandle_t xTaskGetHandle(const char *pcNameToQuery)

	Note 这个函数需要相对较长的时间才能完成，应该很少使用。
	Return 具有人类可读名称pcNameToQuery的任务的句柄。
		   如果未找到匹配的名称，则返回NULL。
		   INCLUDE_xTaskGetHandle必须在FreeRTOSConfig.h中设置为1，这样pcTaskGetGandle()才可用。

---

uxTaskGetStackHighWaterMark

UBaseType_t uxTaskGetStackHighWaterMark(TaskHandle_t xTask)

	返回与xTask相关联的堆栈的高水位标记。
	INCLUDE_uxTaskGetStackHighWaterMark必须在FreeRTOSConfig.h中设置为1，才能使此函数可用。
	返回与xTask相关联的堆栈的高水位标记。也就是说，自任务开始以来，最小可用堆栈空间（也就是说，在32位机器上，值1意味着4字节）。
	返回的数字越小，任务就越接近溢出其堆栈。
	除了它们的返回类型外，uxTaskGetStackHighWaterMark()和 uxTaskGetStackHighWaterMark2()是相同的。
	使用configSTACK_DEPTH_TYPE允许用户确定返回类型。
	它解决了8位类型上的值溢出的问题，而不破坏期望使用8位返回类型的应用程序的向后兼容性。

	Return 自创建xTask引用的任务以来，存在最小的可用堆栈空间（例如，堆栈上的实际空间而不是字节）。
	Parameters
		* xTask：与要检查的堆栈关联的任务的句柄。将xTask设置为NULL以检查调用任务的堆栈。

---

uxTaskGetStackHighWaterMark2

configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2(TaskHandle_t xTask)

	返回与xTask关联的堆栈的开始位置。
	INCLUDE_uxTaskGetStackHighWaterMark2必须在FreeRTOSConfig.h中设置为1，才能使此函数可用。
	
	Return 自创建xTask引用的任务以来，存在最小的可用堆栈空间（例如，堆栈上的实际空间而不是字节）。。
	Parameters
		* xTask：与要检查的堆栈关联的任务的句柄。将xTask设置为NULL以检查调用任务的堆栈。

---

pxTaskGetStackStart

uint8_t *pxTaskGetStackStart(TaskHandle_t xTask)

	返回与xTask关联的堆栈的开始位置。
	INCLUDE_pxTaskGetStackStart必须在FreeRTOSConfig.h中设置为1，才能使此函数可用。
	返回最低堆栈内存地址，不管堆栈是增长还是向下。
	
	Return 指向堆栈开始位置的指针。
	Parameters
		* xTask：返回了与堆栈相关联的任务的句柄。将xTask设置为NULL以返回调用任务的堆栈。

---

vTaskSetApplicationTaskTag

void vTaskSetApplicationTaskTag(TaskHandle_t xTask, 
						    	TaskHookFunction_t pxHookFunction)

	将pxHookFunction设置为任务xTask所使用的任务钩子函数。

	Parameters
		* xTask：设置将XTask传递为空的钩子函数的任务的句柄具有设置调用任务钩子函数的效果。
		* pxHookFunction：指向钩子函数的指针。

---

xTaskGetApplicationTaskTag

TaskHookFunction_t xTaskGetApplicationTaskTag(TaskHandle_t xTask)

	返回分配给任务xTask的pxHookFunction值。不要从中断服务例程调用，而改为调用 xTaskGetApplicationTaskTagFromISR()。

---

xTaskGetApplicationTaskTagFromISR

TaskHookFunction_t xTaskGetApplicationTaskTagFromISR(TaskHandle_t xTask)

	返回分配给任务xTask的pxHookFunction值。可以从中断服务例程中调用。

---

vTaskSetThreadLocalStoragePointer

void vTaskSetThreadLocalStoragePointer(TaskHandle_t xTaskToSet,
									   BaseType_t xIndex, 
									   void *pvValue)
	设置特定于给定任务的本地存储指针。
	每个任务都包含一个指针数组，由FreeRTOSConfig.h中的con-figNUM_THREAD_LOCAL_STORAGE_POINTERS设置进行标注。
	内核本身不使用这些指针，因此应用程序编写器可以使用这些指针用于他们希望使用的任何目的。

	Parameters
		* xTaskToSet：要为设置线程本地存储指针的任务
		* xIndex：要设置的指针的索引，从0到con-figNUM_THREAD_LOCAL_STORAGE_POINTERS-1
		* pvValue：要设置的指针值。

---

pvTaskGetThreadLocalStoragePointer

void *pvTaskGetThreadLocalStoragePointer(TaskHandle_txTaskToQuery, 	
								    BaseType_t xIndex)

---

vTaskSetThreadLocalStoragePointerAndDelCallback

void vTaskSetThreadLocalStoragePointerAndDelCallback(TaskHandle_t xTaskToSet,
													 BaseType_t xIndex, 
													 void *pvValue, 
													 TlsDeleteCallbackFunction_t pvDelCallback)

	设置本地存储指针和删除回调。

---

xTaskCallApplicationTaskHook

BaseType_t xTaskCallApplicationTaskHook(TaskHandle_t xTask, 
										void *pvParameter)

---

xTaskGetIdleTaskHandle

TaskHandle_t xTaskGetIdleTaskHandle(void)

---

uxTaskGetSystemState

UBaseType_t uxTaskGetSystemState(TaskStatus_t *const pxTaskStatusArray, 
							     const UBaseType_t uxArraySize, 
							     uint32_t *const pulTotalRunTime)

---

vTaskList

void vTaskList(char *pcWriteBuffer)

---

vTaskGetRunTimeStats

void vTaskGetRunTimeStats(char *pcWriteBuffer)

---

ulTaskGetIdleRunTimeCounter

uint32_t ulTaskGetIdleRunTimeCounter(void)

---

xTaskGenericNotify

BaseType_t xTaskGenericNotify(TaskHandle_t xTaskToNotify,
 							  uint32_t ulValue, 
 							  eNotifyAction eAction, 
 							  uint32_t *pulPreviousNotificationValue)

---

xTaskGenericNotifyFromISR

BaseType_t xTaskGenericNotifyFromISR(TaskHandle_t xTaskToNotify, 
									 uint32_t ulValue, 
									 eNotifyAction eAction, 
									 uint32_t *pulPreviousNotificationValue,
							         BaseType_t *pxHigherPriorityTaskWoken)

---

xTaskNotifyWait

BaseType_t xTaskNotifyWait(uint32_t ulBitsToClearOnEntry, 
						   uint32_t ulBitsToClearOnExit, 
						   uint32_t *pulNotificationValue, 
						   TickType_t xTicksToWait)

---

vTaskNotifyGiveFromISR

void vTaskNotifyGiveFromISR(TaskHandle_t xTaskToNotify, 
						    BaseType_t *pxHigherPriorityTaskWoken)

---

ulTaskNotifyTake

uint32_t ulTaskNotifyTake(BaseType_t xClearCountOnExit, 
						  TickType_t xTicksToWait)

---

xTaskNotifyStateClear

BaseType_t xTaskNotifyStateClear(TaskHandle_t xTask)

---

宏命令

tskKERNEL_VERSION_NUMBER
tskKERNEL_VERSION_MAJOR
tskKERNEL_VERSION_MINOR
tskKERNEL_VERSION_BUILD
tskMPU_REGION_READ_ONLY
tskMPU_REGION_READ_WRITE
tskMPU_REGION_EXECUTE_NEVER
tskMPU_REGION_NORMAL_MEMORY
tskMPU_REGION_DEVICE_MEMORY
tskNO_AFFINITY
tskIDLE_PRIORITY
	//定义空闲任务所使用的优先级。不能修改。
taskYIELD()	
	//用于强制执行上下文切换的宏。
taskENTER_CRITICAL(x)
	//标记关键代码区域开始的宏。在关键区域时，不能发生优先性上下文切换。
	//注意：这可能会改变堆栈（取决于便携式实现），因此必须小心使用！
taskENTER_CRITICAL_FROM_ISR()
taskENTER_CRITICAL_ISR(mux)
taskEXIT_CRITICAL(x)
	//标记关键代码区域开始的宏。在关键区域时，不能发生优先性上下文切换。
	//注意：这可能会改变堆栈（取决于便携式实现），因此必须小心使用！
taskEXIT_CRITICAL_FROM_ISR(x)
taskEXIT_CRITICAL_ISR(mux)
taskDISABLE_INTERRUPTS()
	//使用宏来禁用所有可屏蔽的中断
taskENABLE_INTERRUPTS()
	//使用宏以启用微控制器中断
taskSCHEDULER_SUSPENDED
taskSCHEDULER_NOT_STARTED
taskSCHEDULER_RUNNING
xTaskNotify(xTaskToNotify, ulValue, eAction)
xTaskNotifyAndQuery(xTaskToNotify, ulValue, eAction, pulPreviousNotifyValue)
xTaskNotifyFromISR(xTaskToNotify, ulValue, eAction, pxHigherPriorityTaskWoken)
xTaskNotifyAndQueryFromISR(xTaskToNotify, ulValue, eAction, pulPreviousNotificationValue,
pxHigherPriorityTaskWoken)
xTaskNotifyGive(xTaskToNotify)

---

类型定义

typedef void *TaskHandle_t
typedef BaseType_t (*TaskHookFunction_t)(void *)
	//定义应用程序任务钩子函数必须符合的原型。
typedef void (*TlsDeleteCallbackFunction_t)(int, void *)
	//本地存储指针删除回调的原型。

---

枚举

eTaskState

enum eTaskState
	eTaskGetState返回的任务状态
Values:
	eRunning = 0
	eReady
	eBlocked
	eSuspended
	eDeleted
	eInvalid

---

eNotifyAction

Values:
	eNoAction = 0
	eSetBits
	eIncrement
	eSetValueWithOverwrite
	eSetValueWithoutOverwrite

---

eSleepModeStatus

eTaskConfirmSleepModeStatus()的可能返回值。
Values:
	eAbortSleep = 0
	eStandardSleep
	eNoTasksWaitingTimeout

---