forked from Imagelibrary/rtems
295 lines
7.5 KiB
Perl
295 lines
7.5 KiB
Perl
@c
|
|
@c COPYRIGHT (c) 1988-1998.
|
|
@c On-Line Applications Research Corporation (OAR).
|
|
@c All rights reserved.
|
|
@c
|
|
@c $Id$
|
|
@c
|
|
|
|
@chapter Rate Monotonic Period Statistics
|
|
|
|
@section Introduction
|
|
|
|
The rate monotonic period statistics manager is an RTEMS support
|
|
component that maintains statistics on the execution characteristics
|
|
of each task using a period. The routines provided by the rate
|
|
monotonic period statistics manager are:
|
|
|
|
@itemize @bullet
|
|
@item @code{Period_usage_Initialize} - Initialize the Period Statistics
|
|
@item @code{Period_usage_Reset} - Reset the Period Statistics
|
|
@item @code{Period_usage_Update} - Update the Statistics for this Period
|
|
@item @code{Period_usage_Dump} - Report Period Statistics Usage
|
|
@end itemize
|
|
|
|
@section Background
|
|
|
|
@section Period Statistics
|
|
|
|
This manager maintains a set of statistics on each period. The following
|
|
is a list of the information kept:
|
|
|
|
@itemize @bullet
|
|
@item @code{id}
|
|
is the id of the period.
|
|
|
|
@item @code{count}
|
|
is the total number of periods executed.
|
|
|
|
@item @code{missed_count}
|
|
is the number of periods that were missed.
|
|
|
|
@item @code{min_cpu_time}
|
|
is the minimum amount of CPU execution time consumed
|
|
on any execution of the periodic loop.
|
|
|
|
@item @code{max_cpu_time}
|
|
is the maximum amount of CPU execution time consumed
|
|
on any execution of the periodic loop.
|
|
|
|
@item @code{total_cpu_time}
|
|
is the total amount of CPU execution time consumed
|
|
by executions of the periodic loop.
|
|
|
|
@item @code{min_wall_time}
|
|
is the minimum amount of wall time that passed
|
|
on any execution of the periodic loop.
|
|
|
|
@item @code{max_wall_time}
|
|
is the maximum amount of wall time that passed
|
|
on any execution of the periodic loop.
|
|
|
|
@item @code{total_wall_time}
|
|
is the total amount of wall time that passed
|
|
during executions of the periodic loop.
|
|
|
|
@end itemize
|
|
|
|
The above information is inexpensive to maintain and can provide very
|
|
useful insights into the execution characteristics of a periodic
|
|
task loop.
|
|
|
|
@subsection Analysis of the Reported Information
|
|
|
|
The period statistics reported must be analyzed by the user in terms
|
|
of what the applications is. For example, in an application where
|
|
priorities are assigned by the Rate Monotonic Algorithm, it would
|
|
be very undesirable for high priority (i.e. frequency) tasks to
|
|
miss their period. Similarly, in nearly any application, if a
|
|
task were supposed to execute its periodic loop every 10 milliseconds
|
|
and it averaged 11 milliseconds, then application requirements
|
|
are not being met.
|
|
|
|
The information reported can be used to determine the "hot spots"
|
|
in the application. Given a period's id, the user can determine
|
|
the length of that period. From that information and the CPU usage,
|
|
the user can calculate the percentage of CPU time consumed by that
|
|
periodic task. For example, a task executing for 20 milliseconds
|
|
every 200 milliseconds is consuming 10 percent of the processor's
|
|
execution time. This is usually enough to make it a good candidate
|
|
for optimization.
|
|
|
|
However, execution time alone is not enough to gauge the value of
|
|
optimizing a particular task. It is more important to optimize
|
|
a task executing 2 millisecond every 10 milliseconds (20 percent
|
|
of the CPU) than one executing 10 milliseconds every 100 (10 percent
|
|
of the CPU). As a general rule of thumb, the higher frequency at
|
|
which a task executes, the more important it is to optimize that
|
|
task.
|
|
|
|
@section Operations
|
|
|
|
@subsection Initializing the Period Statistics
|
|
|
|
The period statistics manager must be explicitly initialized before
|
|
any calls to this manager. This is done by calling the
|
|
@code{Period_usage_Initialize} service.
|
|
|
|
@subsection Updating Period Statistics
|
|
|
|
It is the responsibility of each period task loop to update the statistics
|
|
on each execution of its loop. The following is an example of a
|
|
simple periodic task that uses the period statistics manager:
|
|
|
|
@example
|
|
@group
|
|
rtems_task Periodic_task()
|
|
@{
|
|
rtems_name name;
|
|
rtems_id period;
|
|
rtems_status_code status;
|
|
|
|
name = rtems_build_name( 'P', 'E', 'R', 'D' );
|
|
|
|
(void) rate_monotonic_create( name, &period );
|
|
|
|
while ( 1 ) @{
|
|
if ( rate_monotonic_period( period, 100 ) == TIMEOUT )
|
|
break;
|
|
|
|
/* Perform some periodic actions */
|
|
|
|
/* Report statistics */
|
|
Period_usage_Update( period_id );
|
|
@}
|
|
|
|
/* missed period so delete period and SELF */
|
|
|
|
(void) rate_monotonic_delete( period );
|
|
(void) task_delete( SELF );
|
|
@}
|
|
@end group
|
|
@end example
|
|
|
|
@subsection Reporting Period Statistics
|
|
|
|
The application may dynamically report the period usage for every
|
|
period in the system by calling the @code{Period_usage_Dump} routine.
|
|
This routine prints a table with the following information per period:
|
|
|
|
@itemize @bullet
|
|
@item period id
|
|
@item id of the task that owns the period
|
|
@item number of periods executed
|
|
@item number of periods missed
|
|
@item minimum/maximum/average cpu use per period
|
|
@item minimum/maximum/average wall time per period
|
|
@end itemize
|
|
|
|
The following is an example of the report generated:
|
|
|
|
@example
|
|
@group
|
|
Period information by period
|
|
ID OWNER PERIODS MISSED CPU TIME WALL TIME
|
|
0x28010001 TA1 502 0 0/1/ 1.00 0/0/0.00
|
|
0x28010002 TA2 502 0 0/1/ 1.00 0/0/0.00
|
|
0x28010003 TA3 502 0 0/1/ 1.00 0/0/0.00
|
|
0x28010004 TA4 502 0 0/1/ 1.00 0/0/0.00
|
|
0x28010005 TA5 10 0 0/1/ 0.90 0/0/0.00
|
|
@end group
|
|
@end example
|
|
|
|
@section Routines
|
|
|
|
This section details the rate monotonic period statistics manager's routines.
|
|
A subsection is dedicated to each of this manager's routines
|
|
and describes the calling sequence, related constants, usage,
|
|
and status codes.
|
|
|
|
@page
|
|
@subsection Period_usage_Initialize - Initialize the Period Statistics
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@example
|
|
void Period_usage_Initialize( void );
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
An Ada interface is not currently available.
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading STATUS CODES: NONE
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
This routine allocates the table used to contain the period statistics.
|
|
This table is then initialized by calling the @code{Period_usage_Reset}
|
|
service.
|
|
|
|
@subheading NOTES:
|
|
|
|
This routine invokes the @code{malloc} routine to dynamically allocate
|
|
memory.
|
|
|
|
@page
|
|
@subsection Period_usage_Reset - Reset the Period Statistics
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@example
|
|
void Period_usage_Reset( void );
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
An Ada interface is not currently available.
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading STATUS CODES: NONE
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
This routine re-initializes the period statistics table to its
|
|
default state which is when zero period executions have occurred.
|
|
|
|
@subheading NOTES:
|
|
|
|
NONE
|
|
|
|
@page
|
|
@subsection Period_usage_Update - Update the Statistics for this Period
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@example
|
|
void Period_usage_Update(
|
|
rtems_id id
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
An Ada interface is not currently available.
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading STATUS CODES: NONE
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
The @code{Period_usage_Update} routine must be invoked at the "bottom"
|
|
of each periodic loop iteration to update the statistics.
|
|
|
|
@subheading NOTES:
|
|
|
|
NONE
|
|
|
|
@page
|
|
@subsection Period_usage_Dump - Report Period Statistics Usage
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@example
|
|
void Period_usage_Dump( void );
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
An Ada interface is not currently available.
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading STATUS CODES: NONE
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
This routine prints out a table detailing the period statistics for
|
|
all periods in the system.
|
|
|
|
@subheading NOTES:
|
|
|
|
NONE
|