uxTaskGetSystemState()
[任务实用程序]

task.h

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

必须在 FreeRTOSConfig.h 中将 configUSE_TRACE_FACILITY 中定义为 1，才能使用 uxTaskGetSystemState()。

uxTaskGetSystemState() 为系统中的每个任务填充 TaskStatus_t 结构体。除其他外，TaskStatus_t 结构体包含任务句柄、任务名称、任务优先级、任务状态和任务消耗的运行时间总量等成员。

有关为单个任务（而非每个任务）填充 TaskStatus_t 结构体的定义，请参阅 vTaskGetInfo()。

注意：此函数仅用于调试，因为使用此函数会导致调度程序长时间处于挂起状态。

参数：

pxTaskStatusArray	指向 TaskStatus_t 结构体数组的指针。对于 RTOS 控制下的每个任务，该数组必须至少包含一个 TaskStatus_t 结构体。可使用 uxTaskGetNumberOfTasks() API 函数来确定 RTOS 管理的任务数量。
uxArraySize	pxTaskStatusArray 参数指向的数组的大小。该大小由数组中的索引数（数组中包含的 TaskStatus_t 结构体的数量）指定，而不是由数组中的字节数指定。
pulTotalRunTime	如果在 FreeRTOSConfig.h 中将 configGENERATE_RUN_TIME_STATS 设置为 1，则 uxTaskGetSystemState() 将 *pulTotalRunTime 设置为自目标启动以来的总运行时间（由运行时间统计时钟定义）。可将 pulTotalRunTime 设置为 NULL 以省略总运行时间值。

返回：

由 uxTaskGetSystemState() 填充的 TaskStatus_t 结构体的数量。此值应等于uxTaskGetNumberOfTasks() API 函数返回的数字，但如果在 uxArraySize 参数中传递的值太小，则该值将为零。

用法示例：

/* 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( signed 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 );
   }
}

TaskStatus_t 定义

typedef struct xTASK_STATUS
{
   /* The handle of the task to which the rest of the information in the
   structure relates. */
   TaskHandle_t xHandle;

   /* A pointer to the task's name.  This value will be invalid if the task was
   deleted since the structure was populated! */
   const signed char *pcTaskName;

   /* A number unique to the task. */
   UBaseType_t xTaskNumber;

   /* The state in which the task existed when the structure was populated. */
   eTaskState eCurrentState;

   /* The priority at which the task was running (may be inherited) when the
   structure was populated. */
   UBaseType_t uxCurrentPriority;

   /* The priority to which the task will return if the task's current priority
   has been inherited to avoid unbounded priority inversion when obtaining a
   mutex.  Only valid if configUSE_MUTEXES is defined as 1 in
   FreeRTOSConfig.h. */
   UBaseType_t uxBasePriority;

   /* The total run time allocated to the task so far, as defined by the run
   time stats clock.  Only valid when configGENERATE_RUN_TIME_STATS is
   defined as 1 in FreeRTOSConfig.h. */
   unsigned long ulRunTimeCounter;

   /* Points to the lowest address of the task's stack area. */
   StackType_t *pxStackBase;

   /* The minimum amount of stack space that has remained for the task since
   the task was created.  The closer this value is to zero the closer the task
   has come to overflowing its stack. */
   configSTACK_DEPTH_TYPE usStackHighWaterMark;
} TaskStatus_t;