diff options
Diffstat (limited to 'doc/new_chapters/rtmonuse.t')
| -rw-r--r-- | doc/new_chapters/rtmonuse.t | 294 |
1 files changed, 0 insertions, 294 deletions
diff --git a/doc/new_chapters/rtmonuse.t b/doc/new_chapters/rtmonuse.t deleted file mode 100644 index 05aef493d5..0000000000 --- a/doc/new_chapters/rtmonuse.t +++ /dev/null @@ -1,294 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@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 |