1-xTaskGetHandle
1task.h 2TaskHandle_t xTaskGetHandle( const char *pcNameToQuery );
从任务的名称中查找任务的句柄。
注意：此函数需要较长的时间才能完成，并且只能 为每个任务调用一次。一旦获得了一个任务的句柄， 它就可以被储存在本地以便重新使用。
必须在 FreeRTOSConfig.h 中将 INCLUDE_xTaskGetHandle 设置为 1，xTaskGetHandle() 才可用。
1.1 参数：
pCNAMEToQuery： 将返回句柄的任务的文本名称 （作为标准的以 NULL 结尾的 C 字符串）。
1.2 Returns:
如果可以找到在 pcNameToQuery 中传递名称的任务，则 将返回任务句柄，否则返回 NULL。
2-xTaskGetTickCount
获取系统时间计数器值
1task.h 2volatile TickType_t xTaskGetTickCount( void );
无法从 ISR 调用此函数。使用 xTaskGetTickCountFromISR() 代替。
2.1 Returns:
自 vTaskStartScheduler 被调用起的 tick 数。
3-xTaskGetTickCountFromISR
在中断服务函数中获取时间计数器值
1task.h 2volatile TickType_t xTaskGetTickCountFromISR( void );
xTaskGetTickCount() 的一个版本，可以从 ISR 中调用。
3.1 Returns:
自 vTaskStartScheduler 被调用起的 tick 数。
4-xTaskGetSchedulerState
获取任务调度器的壮态，开启或未开启
1task.h 2BaseType_t xTaskGetSchedulerState( void );
4.1 Returns:
以下常量之一（在 task.h 中定义）：taskSCHEDULER_NOT_STARTED、taskSCHEDULER_RUNNING、taskSCHEDULER_SUSPENDED。
必须在 FreeRTOSConfig.h 中将 INCLUDE_xTaskGetSchedulerState 或 configUSE_TIMERS 设置为 1 才能使用此函数。
5- uxTaskGetNumberOfTasks
获取当前系统中存在的任务数量
1task.h 2UBaseType_t uxTaskGetNumberOfTasks( void );
5.1 Returns:
RTOS 内核当前正在管理的任务数。这包括所有准备就绪、阻塞和挂起的任务。已删除但尚未被闲置任务释放的任务也将包含在计数中。
6- vTaskList
以一种表格的形式输出当前系统中所有任务的详细信息
1task.h 2void vTaskList( char *pcWriteBuffer );
configUSE_TRACE_FACILITY 和 configUSE_STATS_FORMATTING_FUNCTIONS 必须 在 FreeRTOSConfig.h 中定位为 1 ，才可使用此函数。
注意：此函数将在其持续时间内禁用中断。它不是作为 一种正常的应用程序运行时的工具，而是作为调试辅助工具。
vTaskList() 调用 uxTaskGetSystemState()， 然后 将 uxTaskGetSystemState() 生成的原始数据格式化为人类可读的 (ASCII) 表格， 显示每个任务的状态，包括任务的堆栈高水位线（高水位线数字越小， 任务越接近于溢出其堆栈）。
在 ASCII 表中，以下字母用于表示任务的状态：
'B' - 已阻塞
'R' - 准备就绪
'D' - 已删除（等待清理）
'S' - 已挂起或已阻塞，没有超时
vTaskList() 是一个仅为方便起见而提供的实用程序函数。它不是 不是内核的一部分。
6.1 参数：
pcWriteBuffer 一个缓冲区， 上面提到的细节将以 ASCII 形式写入其中。假设此缓冲区 的大小足以容纳产生的报告。大约为每个任务分配 40 字节的缓冲区就足够了。
7-vTaskStartTrace
1task.h 2void vTaskStartTrace( char * pcBuffer, unsigned long ulBufferSize );
[该函数与旧版跟踪工具有关-在 FreeRTOSV7.1.0 中被删除-用户可能会发现较新的 Trace Hook 宏更容易使用，功能也更强大。］
启动 RTOS 内核活动跟踪。跟踪记录何时运行任务的标识。
跟踪文件以二进制格式存储。使用名为 convtrce.exe 的单独 DOS 实用程序将其转换为一个带制表符的文本文件-可以在电子表格中查看和绘制。
7.1 参数：
pcBuffer 跟踪将写入的缓冲区。
ulBufferSize pcBuffer 的大小（以字节为单位）。跟踪将持续到缓冲区已满或 ulTaskEndTrace () 被调用。
8-ulTaskEndTrace
1task.h 2unsigned long ulTaskEndTrace( void );
[该函数与旧版跟踪工具有关-在 FreeRTOSV7.1.0 中被删除-用户可能会发现较新的 Trace Hook 宏更容易使用，功能也更强大。］
停止 RTOS 内核活动跟踪。
8.1 Returns:
已写入跟踪缓冲区的字节数。
9- vTaskGetRunTimeStats
获取每个任务的运行时间
1task.h 2void vTaskGetRunTimeStats( char *pcWriteBuffer );
configGENERATE_RUN_TIME_STATS、configUSE_STATS_FORMATTING_FUNCTIONS 和 configSUPPORT_DYNAMIC_ALLOCATION 必须被 定义为 1，才可使用此函数。然后， 应用程序还必须提供 portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() 和 portGET_RUN_TIME_COUNTER_VALUE 的定义， 以分别配置外设的定时器/计数器和返回定时器的当前计数值。计数器 的频率应该至少是 tick 计数的 10 倍。
注意：此函数将在其持续时间内禁用中断。它 不是作为正常的应用程序运行时的工具，而是作为调试辅助工具。
vTaskGetRunTimeStats() 调用 uxTaskGetSystemState()， 然后将 uxTaskGetSystemState() 生成的原始数据格式化为 人类可读的 (ASCII) 表格， 显示每个任务在运行状态下花费的时间（每个任务消耗了多少 CPU 时间）。数据以 绝对值和百分比值的形式提供。绝对值的分辨率 取决于应用程序提供的运行时间统计时钟的频率。
vTaskGetRunTimeStats() 是一个仅为方便起见而提供的实用程序函数。它 不是内核的一部分。
9.1 参数：
pcWriteBuffer: 一个缓冲区， 执行时间将以 ASCII 形式写入其中。假设此缓冲区足够大， 足以容纳生成的报告。大约为每个任务分配 40 字节的缓冲区 就足够了。
10-vTaskGetIdleRunTimeCounter
1task.h 2TickType_t xTaskGetIdleRunTimeCounter( void );
返回空闲任务的运行时间计数器。此函数可用于 确定空闲任务获得了多少 CPU 时间。
configGENERATE_RUN_TIME_STATS 和 INCLUDE_xTaskGetIdleTaskHandle 必须 定义为 1，才可使用此函数。然后， 应用程序还必须提供 portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() 和 portGET_RUN_TIME_COUNTER_VALUE 的定义， 以分别配置外设的定时器/计数器和返回定时器的当前计数值。建议 确保定时器的频率至少是 tick 计数的 10 倍。
11-vTaskSetApplicationTaskTag
1task. h 2 3void vTaskSetApplicationTaskTag( 4TaskHandle_t xTask, 5TaskHookFunction_t pxTagValue );
configUSE_APPLICATION_TASK_TAG 必须定义为 1，此函数才可用。
可为每个任务分配“标签”值。此值仅供应用程序使用，RTOS 内核本身无法使用此值。RTOS 跟踪宏文档页面提供了一个很好的示例，说明了应用程序如何 使用此功能。
11.1 参数：
xTask 正在向其分配标签值的任务的句柄。将 xTask 作为 NULL 传递会导致将标签分配给调用任务。
pxTagValue 正在分配给任务标签的值。该值为 TaskHookFunction_t 类型，可将函数指针赋值为标签，尽管实际上可以分配任何值。
11.2 示例用法：
1/* 在这个例子中，一个整数被设置为任务标签值。*/ 2void vATask( void *pvParameters ) 3{ 4/* 把标签1分配给自身 */ 5vTaskSetApplicationTaskTag( NULL, ( void * ) 1 ); 6 7for( ;; ) 8{ 9/* 任务代码存放处*/ 10} 11} 12/***********************************************/ 13 14/* 在这个例子中，一个回调函数被分配为任务标记。 15 16首先定义回调函数——它的类型必须是TaskHookFunction_t */ 17static BaseType_t prvExampleTaskHook( void * pvParameter ) 18{ 19/* 执行一些操作-这可以是记录一个值， 20 21更新任务状态、输出值等。*/ 22 23return 0; 24} 25 26/*现在定义将prvExampleTaskHook设置为其钩子/标记值的任务。 27方法上所描述的，这实际上是注册任务回调 28xTaskCallApplicationTaskHook()文档页。 29*/ 30void vAnotherTask( void *pvParameters ) 31{ 32/* 注册回调函数 */ 33vTaskSetApplicationTaskTag( NULL, prvExampleTaskHook ); 34 35for( ;; ) 36{ 37/* 其余的任务代码放在这里。*/ 38} 39} 40 41/* A作为钩子(回调)的一个示例，我们可以让RTOS内核调用在重新调度期间被切换的每个任务的钩子函数。 */ 42#define traceTASK_SWITCHED_OUT() xTaskCallApplicationTaskHook( pxCurrentTCB, 430 )
13- xTaskCallApplicationTaskHook
1task. h 2 3BaseType_t xTaskCallApplicationTaskHook( 4TaskHandle_t xTask, 5void *pvParameter );
configUSE_APPLICATION_TASK_TAG 必须定义为 1，此函数才可用。
可以为每个任务分配“标签”值。通常，此值仅供应用程序使用，并且 RTOS 内核无法访问它。但是，可以 使用标签为任务分配钩子（或回调）函数——通过调用 xTaskCallApplicationTaskHook() 执行该钩子函数。每个任务都可以定义 自己的回调，或者干脆不定义回调。
尽管可以使用第一个函数参数来调用任何任务的钩子函数， 但任务钩子函数最常见的用途是与跟踪钩子宏一起使用，
任务钩子函数必须具有 TaskHookFunction_t 类型，即接受一个 void * 参数，并返回一个 BaseType_t 类型的值。void * 参数可用于 将任何信息传递到钩子函数中。
13.1 参数：
xTask 其钩子函数被调用的任务的句柄。传递 NULL 作为 xTask 将调用与当前执行的任务相关的钩子函数。
pvParameter 要传递给钩子函数的值。这可以是指向一个结构体的指针，也可以是一个数值。
13.2 用法示例：
1/* In this example a callback function is being assigned as the task tag. 2First define the callback function - this must have type TaskHookFunction_t 3as per this example. */ 4static BaseType_t prvExampleTaskHook( void * pvParameter ) 5{ 6/* Perform some action - this could be anything from logging a value, 7updating the task state, outputting a value, etc. */ 8 9return 0; 10} 11 12/* Now define the task that sets prvExampleTaskHook as its hook/tag value. 13This is in fact registering the task callback, as described on the 14xTaskCallApplicationTaskHook() documentation page. */ 15void vAnotherTask( void *pvParameters ) 16{ 17/* Register our callback function. */ 18vTaskSetApplicationTaskTag( NULL, prvExampleTaskHook ); 19 20for( ;; ) 21{ 22/* Rest of task code goes here. */ 23} 24} 25 26/* As an example use of the hook (callback) we can get the RTOS kernel to 27call the hook function of each task that is being switched out during a 28reschedule. */ 29#define traceTASK_SWITCHED_OUT() xTaskCallApplicationTaskHook( pxCurrentTCB, 0 )
14- vTaskSetThreadLocalStoragePointer
设置线程本地存储指针
task. h
1void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet, 2BaseType_t xIndex, 3void *pvValue ) 4
在任务的 线程本地存储数组中设置值。
此功能仅适用于高级用户。
14.1参数：
xTaskToSet 正在写入线程本地数据的任务 的句柄。使用 NULL 作为参数值， 使用 NULL 作为参数值自行读取其线程本地数据。
xIndex 正在写入数据的 线程本地存储数组中的索引。
可用数组索引的数量 由 configNUM_THREAD_LOCAL_STORAGE_POINTERS 编译时 配置常量 FreeRTOSConfig.h。
pvValue 要写入 xIndex 参数 指定的索引的值。
15- pvTaskGetThreadLocalStoragePointer
获取线程本地存储指针
1task. h 2void *pvTaskGetThreadLocalStoragePointer( 3TaskHandle_t xTaskToQuery, 4BaseType_t xIndex );
从任务的线程本地存储数组中获取值。
此功能仅适用于高级用户。
15.1 参数:
xTaskToQuery 从其中读取线程本地数据的任务句柄。任务可以使用NULL作为参数值来读取自己的线程本地数据。
xIndex 读取数据的线程本地存储数组的索引。
可用数组索引的数量由FreeRTOSConfig.h中的confignum_thread_local_storage_pointer编译时配置常量设置。
15.2 返回值:
存储在xTaskToQuery任务的线程本地存储数组的索引位置xIndex中的值。
16- vTaskSetTimeOutState()
1task.h 2void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut );
此功能仅适用于高级用户。
任务可以进入阻止状态以等待事件。通常情况下，任务 不会无限期地在阻止状态下等待，而是会指定一个超时时间段 。如果在任务等待的事件发生之前，超时期限已到， 任务将从阻止状态中删除。
如果任务在等待事件发生的过程中多次进入和退出阻塞状态， 对于事件发生，那么每次任务进入阻止状态时使用的超时时间 必须调整，才能确保花费在 阻止状态的所有时间不会超过最初指定的时时间。xTaskCheckForTimeOut () 执行调整，同时考虑到 诸如滴答数溢出等情况，这种情况会形成容易出错的手动 手动调整容易出错。
vTaskSetTimeOutState() 可与 xTaskCheckForTimeOut() 一起使用。可调用 vTaskSetTimeOutState() 设置初始条件，然后调用 xTaskCheckForTimeOut() 检查超时情况。如果没有超时， 则调整剩余的阻塞时间。
16.1 参数：
pxTimeOut 指向结构体的指针，该结构体将被初始化以保存 确定是否发生超时所需的信息。
17-xTaskCheckForTimeOut()
1task.h 2BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, 3TickType_t * const pxTicksToWait );
此功能仅适用于高级用户。
任务可以进入阻止状态以等待事件。通常情况下，任务 不会无限期地在阻止状态下等待，而是会指定一个超时时间段 。如果在任务等待的事件发生之前，超时期限已到， 任务将从阻止状态中删除。
如果任务在等待事件发生的过程中多次进入和退出阻塞状态， 对于事件发生，那么每次任务进入阻止状态时使用的超时时间 必须调整，才能确保花费在 阻止状态的所有时间不会超过最初指定的时时间。xTaskCheckForTimeOut () 执行调整，同时考虑到 诸如滴答数溢出等情况，这种情况会形成容易出错的手动 调整。
xTaskCheckForTimeOut () 与 vTaskSetTimeOutState () 一起使用。调用 vTaskSetTimeOutState () 以设置初始条件，然后 可以调用 xTaskCheckForTimeOut () 检查超时条件，并且 如果没有发生超时，则调整所述剩余块时间。
17.1 参数：
pxTimeOut 指向一个结构的指针（该结构保存必要的信息） 以确定是否已发生超时。使用 vTaskSetTimeOutState () 将 pxTimeOut 初始化。
pxTicksToWait 来传递调整的块时间，即计入阻止状态已花费的时间后 仍然剩余的时间 。
17.2 Returns:
如果返回 pdTRUE ，则没有块时间剩余，并且发生超时。
如果返回 pdFALSE ，则保留一些块时间，因此未发生超时。
17.3 用法示例：
1/* 驱动库函数用于从Rx缓冲区接收uxWantedBytes由UART中断填充。如果Rx缓冲区中没有足够的字节 2 3然后任务进入阻塞状态，直到通知它有更多数据被放入缓冲区。如果仍然没有足够的数据，那么任务 4 5重新进入Blocked状态，使用xTaskCheckForTimeOut()重新计算阻塞时间，以确保在阻塞状态下花费的总时间 6 7不超过MAX_TIME_TO_WAIT。这一直持续到缓冲区包含at为止最少uxWantedBytes字节，或者在Blocked状态下花费的总时间 8 9到达MAX_TIME_TO_WAIT—此时任务读取多少字节可用的最大uxWantedBytes 10*/ 11size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes ) 12{ 13size_t uxReceived = 0; 14TickType_t xTicksToWait = MAX_TIME_TO_WAIT; 15TimeOut_t xTimeOut; 16 17/*初始化xTimeOut。这记录了输入这个函数的时间。*/ 18vTaskSetTimeOutState( &xTimeOut ); 19 20/* 循环，直到缓冲区包含所需的字节数，或者发生超时。*/ 21while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes ) 22{ 23/* 缓冲区没有包含足够的数据，所以这个任务将进入阻塞状态。调整xTicksToWait以考虑到目前为止在这个函数中花费在Blocked状态的任何时间，以确保花费在Blocked状态的总时间不超过MAX_TIME_TO_WAIT。 */ 24if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE ) 25{ 26/* 在所需字节数可用之前超时，退出循环。*/ 27break; 28} 29 30/* 等待xTicksToWait滴答声的最大值，以通知接收中断已将更多数据放入缓冲区。 */ 31ulTaskNotifyTake( pdTRUE, xTicksToWait ); 32} 33 34/* 尝试将uxWantedBytes从接收缓冲区读入pucBuffer。返回读取的实际字节数(可能小于uxWantedBytes)。 */ 35uxReceived = UART_read_from_receive_buffer( pxUARTInstance, 36pucBuffer, 37uxWantedBytes ); 38 39return uxReceived; 40}
