ECROS API Function OsTaskGetPercentUtil()

UInt16T OsTaskGetPercentUtil( OsHndlT task );

Function OsTaskGetPercentUtil() may be called by the client application to get the percentage of the CPU time that a task is consuming.  The argument must be the task handle, returned by OsNewTask().  The function returns the percentage of time for which the specified task had control of the CPU in a 200 ms measurement period.  This period does not typically end at the call to this function, but may be up to 200 ms in the past.  The format of the function return value is the integer part and the hundredths part of the percentage packed into a 16-bit word.  The integer part is in the least significant byte.  The hundredths part is in the most significant byte.  (This corresponds to big-endian storage.)

If the function argument is zero, the function returns the percentage of the CPU time that the scheduler is using to switch between tasks, evaluate timers and perform other housekeeping activities.  If the argument is a valid task handle, i.e. less than the number of ECROS tasks allocated at compile time, but the task has not been created, the function will quite reasonably return zero.  The handle to the idle task may be passed to the function.

A limitation of the task profiler is that it may not operate correctly if tasks run for more than 25 ms.

Example

The example below shows a function that gets profiler information for a specified task and sends it to the UART0 stream for display on a terminal connected to the system.  Note that the value returned by OsTaskGetPercentUtil() is broken into its two bytes.  The least significant byte is displayed before the decimal point and the most significant byte is displayed after the decimal point using a 2 digit precision specifier.  Thus, a value of 258 (0x0102), for example, will display as 2.01.

static void reportTaskInfo( OsHndlT task )
{
   static rom char  format[] = "task %u: %u.%.2u%% (%uus)\n";
   register UInt16T max;
   register UInt16T pct;

   max = OsTaskGetMaxExecTime( task );
   pct = OsTaskGetPercentUtil( task );
   OsFPrintfLite( OS_UART0, format, task, pct & 0xFF, pct >> 8, max );
}