diff options
Diffstat (limited to 'doc/new_chapters')
| -rw-r--r-- | doc/new_chapters/ChangeLog | 11 | ||||
| -rw-r--r-- | doc/new_chapters/Makefile.am | 10 | ||||
| -rw-r--r-- | doc/new_chapters/gen_section | 6 | ||||
| -rw-r--r-- | doc/new_chapters/rtmonuse.t | 294 |
4 files changed, 13 insertions, 308 deletions
diff --git a/doc/new_chapters/ChangeLog b/doc/new_chapters/ChangeLog index 685702f4ce..1c4202f348 100644 --- a/doc/new_chapters/ChangeLog +++ b/doc/new_chapters/ChangeLog @@ -1,3 +1,14 @@ +2007-05-15 Joel Sherrill <joel.sherrill@oarcorp.com> + + * Makefile.am, gen_section: Integrate Rate Monotonic Statistics and + Period Usage into Rate Monotonic Manager. Added the following + directives: rtems_rate_monotonic_get_statistics, + rtems_rate_monotonic_reset_statistics, + rtems_rate_montonic_reset_all_statistics, + rtems_rate_montonic_report_statistics, and rtems_object_get_name. + Obsoleted the rtems/rtmonuse.h file as a public interface. + * rtmonuse.t: Removed. + 2006-01-19 Ralf Corsepius <ralf.corsepius@rtems.org> * base.t: Remove. diff --git a/doc/new_chapters/Makefile.am b/doc/new_chapters/Makefile.am index db25ec8f22..92eb36da2b 100644 --- a/doc/new_chapters/Makefile.am +++ b/doc/new_chapters/Makefile.am @@ -12,8 +12,7 @@ EDITION = 1 include $(top_srcdir)/project.am include $(top_srcdir)/main.am -GENERATED_FILES = \ - rtmonuse.texi error.texi monitor.texi +GENERATED_FILES = error.texi monitor.texi COMMON_FILES += $(top_srcdir)/common/cpright.texi @@ -22,11 +21,6 @@ FILES = info_TEXINFOS = new_chapters.texi new_chapters_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES) -rtmonuse.texi: rtmonuse.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - error.texi: error.t $(BMENU2) -p "" \ -u "Top" \ @@ -39,7 +33,7 @@ monitor.texi: monitor.t noinst_SCRIPTS = gen_section -EXTRA_DIST = error.t monitor.t rtmonuse.t STATUS TODO \ +EXTRA_DIST = error.t monitor.t STATUS TODO \ $(noinst_SCRIPTS) CLEANFILES += new_chapters.info new_chapters.info-? diff --git a/doc/new_chapters/gen_section b/doc/new_chapters/gen_section index 5950a2e303..dd914f5aea 100644 --- a/doc/new_chapters/gen_section +++ b/doc/new_chapters/gen_section @@ -129,12 +129,6 @@ case ${chapter} in ROUTINES="strcpy strncpy strcat strncat strcmp strncmp strchr strcspn \ strpbrk strrchr strspn strstr strtok stlen" ;; - misc_rtmonuse) - CHAPTER_CAPS="Rate Monotonic Period Statistics" - CHAPTER_LOWER="rate monotonic period statistics" - ROUTINES="Period_usage_Initialize Period_usage_Reset \ - Period_usage_Update Period_usage_Dump" - ;; misc_error) CHAPTER_CAPS="Error Reporting Support" CHAPTER_LOWER="error reporting support" 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 |