FreeRTOS API参考——任务实用程序
Modules
-
uxTaskGetSystemState
-
vTaskGetInfo
-
xTaskGetCurrentTaskHandle
-
xTaskGetIdleTaskHandle
-
uxTaskGetStackHighWaterMark
-
eTaskGetState
-
pcTaskGetName
-
xTaskGetHandle
-
xTaskGetTickCount
-
xTaskGetTickCountFromISR
-
xTaskGetSchedulerState
-
uxTaskGetNumberOfTasks
-
vTaskList
-
vTaskStartTrace
-
ulTaskEndTrace
-
vTaskGetRunTimeStats
-
vTaskGetIdleRunTimeCounter
-
vTaskSetApplicationTaskTag
-
xTaskGetApplicationTaskTag
-
xTaskCallApplicationTaskHook
-
pvTaskGetThreadLocalStoragePointer
-
vTaskSetThreadLocalStoragePointer
-
vTaskSetTimeOutState
-
xTaskCheckForTimeOut
xTaskGetCurrentTaskHandle
task.h
TaskHandle_t xTaskGetCurrentTaskHandle( void );
必须将INCLUDE_xTaskGetCurrentTaskHandle设置为1才能使用此功能。
返回值：
当前正在运行（正在调用）的任务的句柄。
xTaskGetIdleTaskHandle
task.h
TaskHandle_t xTaskGetIdleTaskHandle( void );
必须将INCLUDE_xTaskGetIdleTaskHandle设置为1才能使用此功能。
返回值：
与空闲任务关联的任务句柄。 启动RTOS计划程序时，将自动创建空闲任务。
eTaskGetState
task.h
eTaskState eTaskGetState( TaskHandle_t xTask );
以枚举类型返回执行eTaskGetState（）时任务存在的状态。
必须在FreeRTOSConfig.h中将INCLUDE_eTaskGetState设置为1，eTaskGetState（）才可用。
另请参见vTaskGetInfo（）。
参数：
| xTask |
主题任务（正在查询的任务）的句柄。 |
返回值：
下表列出了eTaskGetState（）将针对xTask参数引用的任务可能存在的每个可能状态返回的值。
| State |
Returned Value |
| Ready |
eReady |
| Running |
eRunning（调用任务正在查询自己的优先级） |
| Blocked |
eBlocked |
| Suspended |
eSuspended |
| Deleted |
eDeleted（TCB的任务正在等待清理） |
pcTaskGetName
task.h
char * pcTaskGetName( TaskHandle_t xTaskToQuery );
从任务的句柄中查找任务的名称。
参数：
| xTaskToQuery |
正在查询任务的句柄。 可以将xTaskToQuery设置为NULL来查询调用任务的名称。 |
返回值：
指向主题任务名称的指针，该名称是标准的以NULL结尾的C字符串。
xTaskGetHandle
task.h
TaskHandle_t xTaskGetHandle( const char *pcNameToQuery );
从任务名称中查找任务的句柄。
注意：此功能需要相对较长的时间才能完成，并且每个任务只能调用一次。 一旦获得任务的句柄，就可以将其存储在本地以供重复使用。
必须将FreeRTOSConfig.h中的INCLUDE_xTaskGetHandle设置为1，才能使xTaskGetHandle（）可用。
参数：
| pcNameToQuery |
将为其返回句柄的任务的文本名称（作为标准的C NULL终止字符串）。 有关设置任务文本名称的信息，请参见xTaskCreate（）和xTaskCreateStatic（）API函数的pcName参数。 |
返回值：
如果可以找到具有在pcNameToQuery中传递的名称的任务，则返回任务的句柄，否则返回NULL。
xTaskGetTickCount
task.h
volatile TickType_t xTaskGetTickCount( void );
无法从ISR调用此函数。 改用xTaskGetTickCountFromISR（）。
返回值：
自调用vTaskStartScheduler以来的滴答计数。
xTaskGetTickCountFromISR
task.h
volatile TickType_t xTaskGetTickCountFromISR( void );
可以从ISR调用的xTaskGetTickCount（）版本。
返回值：
自调用vTaskStartScheduler以来的滴答计数。
xTaskGetSchedulerState
task.h
BaseType_t xTaskGetSchedulerState( void );
返回值：
以下常量之一（在task.h中定义）：taskSCHEDULER_NOT_STARTED，taskSCHEDULER_RUNNING，taskSCHEDULER_SUSPENDED。
要使此功能可用，必须在FreeRTOSConfig.h中将INCLUDE_xTaskGetSchedulerState或configUSE_TIMERS设置为1。
uxTaskGetNumberOfTasks
task.h
UBaseType_t uxTaskGetNumberOfTasks( void );
返回值：
RTOS内核当前正在管理的任务数。 这包括所有准备就绪，已阻止和已暂停的任务。 空闲任务已删除但尚未释放的任务也将包括在计数中。
vTaskList
task.h
void vTaskList( char *pcWriteBuffer );
要使此功能可用，必须在FreeRTOSConfig.h中将configUSE_TRACE_FACILITY和configUSE_STATS_FORMATTING_FUNCTIONS定义为1。有关更多信息，请参见配置部分。
注意：此功能将在其持续时间内禁用中断。它不适合正常的应用程序运行时使用，而是作为调试辅助。
vTaskList（）调用uxTaskGetSystemState（），然后将uxTaskGetSystemState（）生成的原始数据格式化为人类可读（ASCII）表，该表显示每个任务的状态，包括任务堆栈的高水位标记（高水位标记越小，任务越接近其堆栈溢出）。单击此处查看生成的输出示例。
在ASCII表中，以下字母用于表示任务的状态：
-
“ B” –已屏蔽
-
“ R” –准备就绪
-
“ D”-已删除（正在等待清理）
-
“ S” –暂停或被阻止，没有超时
vTaskList（）是仅出于方便目的而提供的实用程序函数。它不被视为内核的一部分。有关实用程序函数的信息，请参见vTaskGetRunTimeStats（），该实用程序函数会生成类似的运行时任务利用率信息表。
参数：
| pcWriteBuffer |
将上述详细信息写入ASCII格式的缓冲区。 假定此缓冲区足够大以包含生成的报告。 每个任务大约40个字节就足够了。 |
vTaskStartTrace
task.h
void vTaskStartTrace( char * pcBuffer, unsigned long ulBufferSize );
【此功能与FreeRTOS V7.1.0中已删除的旧版跟踪实用程序有关，用户可能会发现更易于使用且功能更强大的更新的跟踪挂钩宏。】
启动RTOS内核活动跟踪。 跟踪记录何时运行哪个任务的标识。
跟踪文件以二进制格式存储。 单独的DOS实用程序convtrce.exe可用于将其转换为制表符分隔的文本文件，该文件可在电子表格中查看和绘制。
参数：
| pcBuffer |
跟踪将写入其中的缓冲区。 |
| ulBufferSize |
pcBuffer的大小（以字节为单位）。 跟踪将一直持续到缓冲区已满或调用ulTaskEndTrace（）为止。 |
ulTaskEndTrace
task.h
unsigned long ulTaskEndTrace( void );
【此功能与FreeRTOS V7.1.0中已删除的旧版跟踪实用程序有关，用户可能会发现更易于使用且功能更强大的更新的跟踪挂钩宏。】
停止RTOS内核活动跟踪。 请参见vTaskStartTrace（）。
返回值：
已写入跟踪缓冲区的字节数。
vTaskGetRunTimeStats
task.h
void vTaskGetRunTimeStats( char *pcWriteBuffer );
有关此功能的完整说明，请参见“运行时统计”页面。
为了使此功能可用，必须将configGENERATE_RUN_TIME_STATS和configUSE_STATS_FORMATTING_FUNCTIONS都定义为1。然后，应用程序还必须提供portCONFIGURE_TIMER_FOR_RUN_TIME_STATS（）和portGET_RUN_TIME_COUNTER_VALUE的定义，以配置外设定时器/计数器并分别返回定时器的当前计数值。计数器应至少是滴答计数频率的10倍。
注意：此功能将在其持续时间内禁用中断。它不适合正常的应用程序运行时使用，而是作为调试辅助。
vTaskGetRunTimeStats（）调用uxTaskGetSystemState（），然后将uxTaskGetSystemState（）生成的原始数据格式化为人类可读（ASCII）表，该表显示每个任务在运行状态下所花费的时间（每个任务所消耗的CPU时间） 。数据以绝对值和百分比值形式提供。绝对值的分辨率取决于应用程序提供的运行时统计时钟的频率。
vTaskGetRunTimeStats（）是仅出于方便目的而提供的实用程序函数。它不被视为内核的一部分。有关生成每个任务状态信息的实用程序功能，请参见vTaskList（）。
参数：
| pcWriteBuffer |
执行时间将以ASCII形式写入的缓冲区。 假定此缓冲区足够大以包含生成的报告。 每个任务大约40个字节就足够了。 |
vTaskGetIdleRunTimeCounter
task.h
TickType_t xTaskGetIdleRunTimeCounter( void );
返回空闲任务的运行时计数器。 此功能可用于确定空闲任务接收了多少CPU时间。 有关运行时状态功能的完整说明，请参见“运行时状态”页面。
为了使该功能可用，必须将configGENERATE_RUN_TIME_STATS和INCLUDE_xTaskGetIdleTaskHandle都定义为1。 然后，应用程序还必须提供portCONFIGURE_TIMER_FOR_RUN_TIME_STATS（）和portGET_RUN_TIME_COUNTER_VALUE的定义，以配置外设定时器/计数器并分别返回定时器的当前计数值。 建议使计时器至少是滴答计数频率的10倍。
vTaskSetApplicationTaskTag
task. h
void vTaskSetApplicationTaskTag(
TaskHandle_t xTask,
TaskHookFunction_t pxTagValue );
必须将configUSE_APPLICATION_TASK_TAG定义为1，此功能才能使用。 有关更多信息，请参见RTOS配置文档。
可以为每个任务分配一个“标签”值。 该值仅用于应用程序– RTOS内核本身不以任何方式使用它。 RTOS跟踪宏文档页面提供了一个很好的示例，说明应用程序如何使用此功能。
参数：
| xTask |
为其分配了标签值的任务的句柄。 将xTask传递为NULL会将标记分配给调用任务。 |
| pxTagValue |
分配给任务标签的值。 这是TaskHookFunction_t类型，允许将功能指针分配为标签，尽管实际上可以分配任何值。 请参见下面的示例。 |
用法示例：
/* In this example an integer is set as the task tag value.
See the RTOS trace hook macros documentation page for an
example how such an assignment can be used. */
void vATask( void *pvParameters )
{
/* Assign a tag value of 1 to myself. */
vTaskSetApplicationTaskTag( NULL, ( void * ) 1 );
for( ;; )
{
/* Rest of task code goes here. */
}
}
/***********************************************/
/* In this example a callback function is being assigned as the task tag.
First define the callback function - this must have type TaskHookFunction_t
as per this example. */
static BaseType_t prvExampleTaskHook( void * pvParameter )
{
/* Perform some action - this could be anything from logging a value,
updating the task state, outputting a value, etc. */
return 0;
}
/* Now define the task that sets prvExampleTaskHook as its hook/tag value.
This is in fact registering the task callback, as described on the
xTaskCallApplicationTaskHook() documentation page. */
void vAnotherTask( void *pvParameters )
{
/* Register our callback function. */
vTaskSetApplicationTaskTag( NULL, prvExampleTaskHook );
for( ;; )
{
/* Rest of task code goes here. */
}
}
/* As an example use of the hook (callback) we can get the RTOS kernel to call the
hook function of each task that is being switched out during a reschedule. */
#define traceTASK_SWITCHED_OUT() xTaskCallApplicationTaskHook( pxCurrentTCB, 0 )
xTaskCallApplicationTaskHook
task. h
BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter );
必须将configUSE_APPLICATION_TASK_TAG定义为1，此功能才能使用。 有关更多信息，请参见RTOS配置文档。
可以为每个任务分配一个“标签”值。 通常，此值仅供应用程序使用，RTOS内核不会访问它。 但是，可以使用标记将钩子（或回调）函数分配给任务-通过调用xTaskCallApplicationTaskHook（）执行钩子函数。 每个任务可以定义自己的回调，也可以根本不定义回调。
尽管可以使用第一个函数参数来调用任何任务的钩子函数，但是任务钩子函数最常见的用法是使用跟踪钩子宏，如以下示例所示。
任务挂钩函数必须具有TaskHookFunction_t类型，即带有void *参数，并返回BaseType_t类型的值。 void *参数可用于将任何信息传递给hook函数。
参数：
| xTask |
正在调用其挂钩函数的任务的句柄。 将NULL作为xTask传递时，将调用与当前正在执行的任务相关联的hook函数。 |
| pvParameter |
传递给挂钩函数的值。 这可以是指向结构的指针，也可以只是数字值。 |
用法示例：
/* In this example a callback function is being assigned as the task tag.
First define the callback function - this must have type TaskHookFunction_t
as per this example. */
static BaseType_t prvExampleTaskHook( void * pvParameter )
{
/* Perform some action - this could be anything from logging a value,
updating the task state, outputting a value, etc. */
return 0;
}
/* Now define the task that sets prvExampleTaskHook as its hook/tag value.
This is in fact registering the task callback, as described on the
xTaskCallApplicationTaskHook() documentation page. */
void vAnotherTask( void *pvParameters )
{
/* Register our callback function. */
vTaskSetApplicationTaskTag( NULL, prvExampleTaskHook );
for( ;; )
{
/* Rest of task code goes here. */
}
}
/* As an example use of the hook (callback) we can get the RTOS kernel to
call the hook function of each task that is being switched out during a
reschedule. */
#define traceTASK_SWITCHED_OUT() xTaskCallApplicationTaskHook( pxCurrentTCB, 0 )
vTaskSetThreadLocalStoragePointer
task. h
void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet,
BaseType_t xIndex,
void *pvValue )
在任务的线程本地存储阵列中设置一个值。
此功能仅适用于高级用户。
参数：
| xTaskToSet |
线程本地数据正在写入的任务的句柄。 通过使用NULL作为参数值，任务可以写入其自己的线程本地数据。 |
| xIndex |
线程本地存储阵列中要写入数据的索引。 可用数组索引的数量由FreeRTOSConfig.h中的configNUM_THREAD_LOCAL_STORAGE_POINTERS编译时配置常量设置。 |
| pvValue |
要写入由xIndex参数指定的索引的值。 |
用法示例：
请参阅线程本地存储阵列文档页面上提供的示例。
pvTaskGetThreadLocalStoragePointer
task. h
void *pvTaskGetThreadLocalStoragePointer(
TaskHandle_t xTaskToQuery,
BaseType_t xIndex );
从任务的线程本地存储阵列中检索值。
此功能仅适用于高级用户。
参数：
| xTaskToQuery |
从中读取线程本地数据的任务的句柄。 通过使用NULL作为参数值，任务可以读取自己的线程本地数据。 |
| xIndex |
到线程本地存储阵列中的索引，将从中读取数据。 可用数组索引的数量由FreeRTOSConfig.h中的configNUM_THREAD_LOCAL_STORAGE_POINTERS编译时配置常量设置。 |
返回值：
存储在任务xTaskToQuery的线程本地存储数组的索引位置xIndex中的值。
用法示例：
请参阅线程本地存储阵列文档页面上提供的示例。
vTaskSetTimeOutState()
task.h
void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut );
此功能仅适用于高级用户。
任务可以进入阻止状态以等待事件。通常，任务不会无限期地处于“阻塞”状态，而是将指定超时期限。如果超时时间在任务等待事件发生之前到期，则该任务将从“阻塞”状态中删除。
如果任务在等待事件发生时多次进入和退出“阻止”状态，则必须调整每次任务进入“阻止”状态所用的超时时间，以确保在“阻止”状态下花费的所有时间总计不超过最初指定的超时期限。 xTaskCheckForTimeOut（）执行调整时要考虑偶发计数溢出之类的偶发事件，否则这会使手动调整容易出错。
vTaskSetTimeOutState（）与xTaskCheckForTimeOut（）一起使用。调用vTaskSetTimeOutState（）设置初始条件，之后可以调用xTaskCheckForTimeOut（）来检查超时条件，并在未发生超时的情况下调整剩余的块时间。
参数：
| pxTimeOut |
指向结构的指针，该结构将被初始化以保存确定是否发生超时所必需的信息。 |
用法示例：
xTaskCheckForTimeOut（）文档页面上提供了一个示例。
xTaskCheckForTimeOut()
task.h
BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut,
TickType_t * const pxTicksToWait );
此功能仅适用于高级用户。
任务可以进入阻止状态以等待事件。通常，任务不会无限期地处于“阻塞”状态，而是将指定超时期限。如果超时时间在任务等待事件发生之前到期，则该任务将从“阻塞”状态中删除。
如果任务在等待事件发生时多次进入和退出“阻止”状态，则必须调整每次任务进入“阻止”状态所用的超时时间，以确保在“阻止”状态下花费的所有时间总计不超过最初指定的超时期限。 xTaskCheckForTimeOut（）执行调整时要考虑偶发计数溢出之类的偶发事件，否则这会使手动调整容易出错。
xTaskCheckForTimeOut（）与vTaskSetTimeOutState（）一起使用。调用vTaskSetTimeOutState（）设置初始条件，之后可以调用xTaskCheckForTimeOut（）来检查超时条件，并在未发生超时的情况下调整剩余的块时间。
参数：
| pxTimeOut |
指向结构的指针，该结构保存确定是否发生超时所需的信息。 使用vTaskSetTimeOutState（）初始化pxTimeOut。 |
| pxTicksToWait |
用于传递调整后的阻止时间，这是考虑到已经处于“阻止”状态的时间之后剩余的阻止时间。 |
返回值：
如果返回pdTRUE，则没有块时间剩余，并且发生了超时。
如果返回pdFALSE，则剩余一些块时间，因此不会发生超时。
用法示例：
/* Driver library function used to receive uxWantedBytes from an Rx buffer that
is filled by a UART interrupt. If there are not enough bytes in the Rx buffer
then the task enters the Blocked state until it is notified that more data has
been placed into the buffer. If there is still not enough data then the task
re-enters the Blocked state, and xTaskCheckForTimeOut() is used to re-calculate
the Block time to ensure the total amount of time spent in the Blocked state does
not exceed MAX_TIME_TO_WAIT. This continues until either the buffer contains at
least uxWantedBytes bytes, or the total amount of time spent in the Blocked state
reaches MAX_TIME_TO_WAIT – at which point the task reads however many bytes are
available up to a maximum of uxWantedBytes. */
size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes )
{
size_t uxReceived = 0;
TickType_t xTicksToWait = MAX_TIME_TO_WAIT;
TimeOut_t xTimeOut;
/* Initialize xTimeOut. This records the time at which this function was
entered. */
vTaskSetTimeOutState( &xTimeOut );
/* Loop until the buffer contains the wanted number of bytes, or a timeout
occurs. */
while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes )
{
/* The buffer didn't contain enough data so this task is going to
enter the Blocked state. Adjusting xTicksToWait to account for any time
that has been spent in the Blocked state within this function so far to
ensure the total amount of time spent in the Blocked state does not exceed
MAX_TIME_TO_WAIT. */
if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE )
{
/* Timed out before the wanted number of bytes were available, exit the
loop. */
break;
}
/* Wait for a maximum of xTicksToWait ticks to be notified that the receive
interrupt has placed more data into the buffer. */
ulTaskNotifyTake( pdTRUE, xTicksToWait );
}
/* Attempt to read uxWantedBytes from the receive buffer into pucBuffer. The
actual number of bytes read (which might be less than uxWantedBytes) is
returned. */
uxReceived = UART_read_from_receive_buffer( pxUARTInstance,
pucBuffer,
uxWantedBytes );
return uxReceived;
}