1 files changed, 294 insertions, 0 deletions
diff --git a/doc/new_chapters/rtmonuse.t b/doc/new_chapters/rtmonuse.t
new file mode 100644
index 0000000000..a8cce5c48d
--- /dev/null
+++ b/doc/new_chapters/rtmonuse.t
@@ -0,0 +1,294 @@
+@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