9，FreeRTOS任务相关API函数

最新推荐文章于 2026-06-22 15:50:24 发布

原创最新推荐文章于 2026-06-22 15:50:24 发布 · 679 阅读

10 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#嵌入式硬件 #FreeRTOS #RTOS #stm32

FreeRTOS学习笔记专栏收录该内容

26 篇文章

订阅专栏

本节介绍FreeRTOS中任务相关的一些API函数以及用法，具体内容也可以参考FreeRTOS官网API介绍。

1.获取任务优先级函数

函数说明:

用于获取指定任务的任务优先级，若使用此函数，需在FreeRTOSConfig.h 文件中设置配置项INCLUDE_uxTaskPriorityGet 为1。

输入为查询的任务句柄,输出为任务优先级。

UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask );

应用示例:

void vATaskFunction( void * pvParams )
{
    TaskHandle_t xHandle;

    ( void ) pvParams;

    // Create a task, storing the handle.
    xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );

    // ...

    // Use the handle to obtain the priority of the created task.
    // It was created with tskIDLE_PRIORITY, but may have changed
    // it itself.
    if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
    {
        // The task has changed its priority.
    }

    // ...

    // Is our priority higher than the created task?
    if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
    {
        // Our priority (obtained using NULL handle) is higher.
    }
}

2.设置任务优先级

函数说明:

用于设置指定任务的优先级，若使用此函数，需在F reeRTOSConfig.h 文件中设置配置项INCLUDE_vTaskPrioritySet 为1。

输入为指定任务的任务句柄,新的任务优先级。

void vTaskPrioritySet( TaskHandle_t xTask,
                       UBaseType_t uxNewPriority );

应用示例:

void vAFunction( void )  
{  
    TaskHandle_t xHandle;  

    // Create a task, storing the handle.  
    xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );  

    // ...  

    // Use the handle to raise the priority of the created task.  
    vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 )  

    // ...  

    // Use a NULL handle to raise our priority to the same value.  
    vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 );  
 }

3.获取系统中的任务数量

函数说明:

用于获取所有任务的状态信息，若使用此函数，需在F reeRTOSConfig.h 文件中设置配置项configUSE_TRACE_FACILITY 为1。

输入为指定任务的接收变量数组的首地址,数组大小,获取系统总运行时间。返回值为获取信息的任务数量。

第一个函数:

UBaseType_t uxTaskGetNumberOfTasks(void);

第二个函数:

UBaseType_t uxTaskGetSystemState(
                       TaskStatus_t * const pxTaskStatusArray,
                       const UBaseType_t uxArraySize,
                       unsigned long * const pulTotalRunTime );

应用示例:

/* This example demonstrates how a human readable table of run time stats
   information is generated from raw data provided by uxTaskGetSystemState().
   The human readable table is written to pcWriteBuffer. (see the vTaskList()
   API function which actually does just this). */
void vTaskGetRunTimeStats( char *pcWriteBuffer )
{
    TaskStatus_t *pxTaskStatusArray;
    volatile UBaseType_t uxArraySize, x;
    unsigned long ulTotalRunTime, ulStatsAsPercentage;

   /* Make sure the write buffer does not contain a string. */
   *pcWriteBuffer = 0x00;

   /* Take a snapshot of the number of tasks in case it changes while this
      function is executing. */
   uxArraySize = uxTaskGetNumberOfTasks();

   /* Allocate a TaskStatus_t structure for each task. An array could be
      allocated statically at compile time. */
   pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ) );

   if( pxTaskStatusArray != NULL )
   {
      /* Generate raw status information about each task. */
      uxArraySize = uxTaskGetSystemState( pxTaskStatusArray,
                                 uxArraySize,
                                 &ulTotalRunTime );

      /* For percentage calculations. */
      ulTotalRunTime /= 100UL;

      /* Avoid divide by zero errors. */
      if( ulTotalRunTime > 0 )
      {
         /* For each populated position in the pxTaskStatusArray array,
            format the raw data as human readable ASCII data. */
         for( x = 0; x < uxArraySize; x++ )
         {
            /* What percentage of the total run time has the task used?
               This will always be rounded down to the nearest integer.
               ulTotalRunTimeDiv100 has already been divided by 100. */
            ulStatsAsPercentage =
                  pxTaskStatusArray[ x ].ulRunTimeCounter / ulTotalRunTime;

            if( ulStatsAsPercentage > 0UL )
            {
               sprintf( pcWriteBuffer, "%stt%lutt%lu%%rn",
                                 pxTaskStatusArray[ x ].pcTaskName,
                                 pxTaskStatusArray[ x ].ulRunTimeCounter,
                                 ulStatsAsPercentage );
            }
            else
            {
               /* If the percentage is zero here then the task has
                  consumed less than 1% of the total run time. */
               sprintf( pcWriteBuffer, "%stt%lutt<1%%rn",
                                 pxTaskStatusArray[ x ].pcTaskName,
                                 pxTaskStatusArray[ x ].ulRunTimeCounter );
            }

            pcWriteBuffer += strlen( ( char * ) pcWriteBuffer );
         }
      }

      /* The array is no longer needed, free the memory it consumes. */
      vPortFree( pxTaskStatusArray );
   }
}

4.获取指定单个任务信息

函数说明:

用于获取指定任务的任务信息，若使用此函数，需在FreeRTOSConfig.h 文件中设置配置项configUSE_TRACE_FACILITY 为1。

输入为指定任务的句柄,接受任务信息的变量,任务战历史剩余最小值,任务状态。

void vTaskGetInfo( TaskHandle_t xTask,
                   TaskStatus_t *pxTaskStatus,
                   BaseType_t xGetFreeStackSpace,
                   eTaskState eState );

任务状态包含如下:

typedef enum {     eRunning = 0, /* 运行态 */ 
                eReady, /* 就绪态 */ 
                eBlocked, /* 阻塞态 */ 
                eSuspended, /* 挂起态 */ 
                eDeleted, /* 任务被删除 */ 
                eInvalid /* 非法值 */ 
} eTaskState;

应用示例:

void vAFunction( void )
{
    TaskHandle_t xHandle;
    TaskStatus_t xTaskDetails;

    /* Obtain the handle of a task from its name. */
    xHandle = xTaskGetHandle( "Task_Name" );

    /* Check the handle is not NULL. */
    configASSERT( xHandle );

    /* Use the handle to obtain further information about the task. */
    vTaskGetInfo( /* The handle of the task being queried. */
                  xHandle,
                  /* The TaskStatus_t structure to complete with information
                     on xTask. */
                  &xTaskDetails,
                  /* Include the stack high water mark value in the
                     TaskStatus_t structure. */
                  pdTRUE,
                  /* Include the task state in the TaskStatus_t structure. */
                  eInvalid );
}

5.根据任务名获取该任务句柄

函数说明:

于通过任务名获取任务句柄，若使用此函数，需在FreeRTOSConfig.h 文件中设置配置项INCLUDE_xTaskGetHandle 为1。

输入为任务名。返回值为任务句柄。

TaskHandle_t xTaskGetHandle(const char * pcNameToQuery);

6.获取当前任务的任务句柄

函数说明:

用于获取当前系统正在运行的任务的任务句柄，若使用此函数，需在FreeRTOSConfig.h 文件中设置配置项INCLUDE_xTaskGetCurrentTaskHandle 为1。

TaskHandle_t xTaskGetCurrentTaskHandle(void);

7.获取任务的任务栈历史剩余最小值

函数说明:

获取指定任务的任务栈的历史剩余最小值，若使用此函数，需在FreeRTOSConfig.h 文件中设置配置项INCLUDE_uxTaskGetStackHighWaterMark 为1。

输入为指定任务的任务句柄。输出为任务栈的历史剩余最小值。

UBaseType_t uxTaskGetStackHighWaterMark
 ( TaskHandle_t xTask );

应用示例:

    void vTask1( void * pvParameters )
    {
        UBaseType_t uxHighWaterMark;

        /* Inspect our own high water mark on entering the task. */
        uxHighWaterMark = uxTaskGetStackHighWaterMark( NULL );

        for( ;; )
        {
            /* Call any function. */
            vTaskDelay( 1000 );

            /* Calling the function will have used some stack space, we would 
               therefore now expect uxTaskGetStackHighWaterMark() to return a 
               value lower than when it was called on entering the task. */
            uxHighWaterMark = uxTaskGetStackHighWaterMark( NULL );
        }
    }

8.获取任务状态

函数说明:

于获取指定任务的状态，若使用此函数，需在FreeRTOSConfig.h 文件中设置配置项INCLUDE_eTaskGetState 为1。

输入为指定任务的任务句柄。返回值为任务状态。

eTaskState eTaskGetState(TaskHandle_t xTask);

9..以"表格"形式获取所有任务的信息

函数说明:

以“表格”的形式获取系统中任务的信息，若使用此函数，需在FreeRTOSConfig.h
文件中同时设置配置项configUSE_TRACE_FACILITY 和配置configUSE_STATS_FORMATTING_FUNCTIONS 为1。

输入为接收任务信息的缓存指针。

void vTaskList(char * pcWriteBuffer);

10.获取任务的运行时间

函数说明:

获取指定任务的运行时间、运行状态等信息，若使用此函数，需在F reeRTOSConfig.h 文件中同时设置配置项configGENERATE_RUN_TIME_STAT S 、configUSE_STATS_FORMATTING_FUNCTIONS 、configSUPPORT_DYNAMIC_ALLOCATION
为1。

输入为接收任务运行时间和运行状态信息的缓存指针。

void vTaskGetRunTimeStats(char * pcWriteBuffer);