15-FreeRTOS任务应用函数（1）

1-获取系统的任务状态（uxTaskGetSystemState()）

1.1 函数描述

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

configUSE_TRACE_FACILITY 必须设置为1
该函数向TaskStatus_t结构体填充相关信息，系统中每一个任务的信息都可以填充到TaskStatus_t结构体数组中，数组大小由uxArraySize指定。结构体TaskStatus_t定义如下：

typedef struct xTASK_STATUS
{
   /* 任务句柄 */
   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;

注意，这个函数仅用来调试用，调用此函数会挂起所有任务，直到函数最后才恢复挂起的任务，因此任务可能被挂起很长时间。在文件FreeRTOSConfig.h中，宏configUSE_TRACE_FACILITY必须设置为1，此函数才有效。

1.2 参数描述

pxTaskStatusArray：指向TaskStatus_t类型的结构体数组。这个数组至少要包含1个元素。RTOS控制的任务数量可以使用API函数uxTaskGetNumberOfTasks()获取。
uxArraySize：参数pxTaskStatusArray指向的数组大小，也就是该数组的索引数目。
pulTotalRunTime：如果在文件FreeRTOSConfig.h中设置宏configGENERATE_RUN_TIME_STATS为1，则该函数将总运行时间写入*pulTotalRunTime中。pulTotalRunTime可以设置为NULL，表示忽略总运行时间。
返回值：由uxTaskGetSystemState()填充的TaskStatus_t结构的数量。这个值应该等于uxTaskGetNumberOfTasks() API函数返回的值，但是如果uxArraySize参数传递的值太小，它将为零。

1.3 用例

/*本例演示如是使用uxTaskGetSystemState()函数来获取运行时间信息，并将其转化为程序员更易识别的字符格式，这些转化后的字符保存到pcWriteBuffer中。*/
void vTaskGetRunTimeStats(signed char *pcWriteBuffer )
{
   TaskStatus_t*pxTaskStatusArray;
   volatileUBaseType_t uxArraySize, x;
   unsignedlong ulTotalRunTime, ulStatsAsPercentage;
 
   /* 防御性代码，确保字符串有合理的结束*/
  *pcWriteBuffer = 0x00;
 
   /* 获取任务总数目*/
  uxArraySize = uxTaskGetNumberOfTasks ();
 
   /*为每个任务的TaskStatus_t结构体分配内存，也可以静态的分配一个足够大的数组 */
  pxTaskStatusArray = pvPortMalloc( uxArraySize * sizeof( TaskStatus_t ));
 
   if(pxTaskStatusArray != NULL )
   {
      /*获取每个任务的状态信息 */
     uxArraySize = uxTaskGetSystemState( pxTaskStatusArray, uxArraySize,&ulTotalRunTime );
 
      /* 百分比计算 */
     ulTotalRunTime /= 100UL;
 
      /* 避免除零错误 */
      if(ulTotalRunTime > 0 )
      {
         /* 将获得的每一个任务状态信息部分的转化为程序员容易识别的字符串格式*/
        for( x = 0; x < uxArraySize; x++ )
         {
           /* 计算任务运行时间与总运行时间的百分比。*/
           ulStatsAsPercentage = pxTaskStatusArray[ x ].ulRunTimeCounter /ulTotalRunTime;
 
           if( ulStatsAsPercentage > 0UL )
           {
              sprintf( pcWriteBuffer, "%s\t\t%lu\t\t%lu%%\r\n",
                                pxTaskStatusArray[ x ].pcTaskName,
                                pxTaskStatusArray[ x ].ulRunTimeCounter,
                                ulStatsAsPercentage );
           }
           else
           {
              /* 任务运行时间不足总运行时间的1%*/
              sprintf( pcWriteBuffer, "%s\t\t%lu\t\t<1%%\r\n",
                                pxTaskStatusArray[ x ].pcTaskName,
                                 pxTaskStatusArray[x ].ulRunTimeCounter );
           }
 
           pcWriteBuffer += strlen( ( char * ) pcWriteBuffer );
         }
      }
 
      /* 释放之前申请的内存*/
     vPortFree( pxTaskStatusArray );
   }
}

2-获取任务消息（vTaskGetInfo()）

2.1 函数描述

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

configUSE_TRACE_FACILITY必须设置1
uxTaskGetSystemState()为系统中的每个任务填充TaskStatus_t结构，而vTaskGetInfo()仅为单个任务填充TaskStatus_t结构。TaskStatus_t结构包含任务句柄的成员、任务名称、任务优先级、任务状态和任务消耗的运行时间总量。
注意:此函数仅用于调试，因为使用它会导致调度器在较长时间内保持挂起状态。

2.2 参数描述

xTask ： 正在查询任务的句柄。将xTask设置为NULL将返回调用任务的信息。
**pxTaskStatus：**由pxTaskStatus指向的TaskStatus_t结构体将被xTask参数中传递的句柄所引用的任务的信息填充。
xGetFreeStackSpace： TaskStatus_t结构包含一个成员，用于报告正在查询的任务的堆栈高水位标记。堆栈高水位标志是曾经存在的堆栈空间的最小值，因此该数字越接近零，任务就越接近溢出堆栈。计算堆栈高水位标志需要相对较长的时间，并且可能使系统暂时无响应——因此提供xGetFreeStackSpace参数以允许跳过高水位标志检查。如果xGetFreeStackSpace没有设置为pdFALSE，高水位值只会被写入TaskStatus_t结构。
eState： TaskStatus_t结构体包含一个成员，用于报告正在查询的任务的状态。获取任务状态没有简单的赋值那么快——因此提供eState参数以允许从TaskStatus_t结构中省略状态信息。要获得状态信息，请将eState设置为eInvalid—否则在eState中传递的值将作为TaskStatus_t结构中的任务状态报告。

2.3 用例

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

    /* 从任务的名称中获取任务句柄。*/
    xHandle = xTaskGetHandle( "Task_Name" );

    /* 检查句柄是不是任务本身. */
    configASSERT( xHandle );

    /* 使用句柄可以获得关于任务的进一步信息。 */
    vTaskGetInfo( /* 正在查询任务的句柄。 */
                  xHandle,
                  /* 要用信息完成的TaskStatus_t结构xTask。 */
                  &xTaskDetails,
                  /* Include the stack high water mark value in the
                  TaskStatus_t structure. */
                  pdTRUE,
                  /* 在TaskStatus_t结构中包含任务状态*/
                  eInvalid );
}

2.4 The TaskStatus_t definition

typedef struct xTASK_STATUS
{
   /* 对象中的其余信息所归属的任务句柄结构有关。*/
   TaskHandle_t xHandle;

   /*指向任务名称的指针。这个值将无效，如果任务被删除，因为结构已填充! */
   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;