RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

2007-05-15 Joel Sherrill <joel.sherrill@oarcorp.com>

Browse Source 
* user/Makefile.am, user/concepts.t, user/rtmon.t: 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.
This commit is contained in:
Joel Sherrill
2007-05-15 20:17:21 +00:00
parent 05ddbf2565
commit 35a81f8814
4 changed files with 311 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
doc/ChangeLog
View File

@@ -1,3 +1,13 @@
2007-05-15 Joel Sherrill <joel.sherrill@oarcorp.com>
* user/Makefile.am, user/concepts.t, user/rtmon.t: 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.
2007-05-11 Joel Sherrill <joel.sherrill@OARcorp.com>
* user/.cvsignore, user/cpuuse.t, user/stackchk.t: Stack checker and

2
doc/user/Makefile.am
View File

@@ -140,7 +140,7 @@ rtmon.texi: rtmon.t
-n "Barrier Manager" < $< > $@
barrier.texi: barrier.t
$(BMENU2) -p "Rate Monotonic Manager RATE_MONOTONIC_GET_STATUS - Obtain status information on period" \
$(BMENU2) -p "Rate Monotonic Manager RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report" \
-u "Top" \
-n "Board Support Packages" < $< > $@

26
doc/user/concepts.t
View File

@@ -76,6 +76,32 @@ assign meaningful ASCII names to each task. A more convenient
approach would be to name them the binary values one through
one-hundred, respectively.
@findex rtems_get_object_name
RTEMS provides a helper routine, @code{@value{DIRPREFIX}get_object_name},
which can be used to obtain the name of any RTEMS object using just
its ID. This routine attempts to convert the name into a printable string.
@ifset is-C
The following example illustrates the use of this method to print
an object name:
@example
#include <rtems.h>
#include <rtems/bspIo.h>
void print_name(rtems_id the_object)
@{
char buffer[10]; /* name assumed to be 10 characters or less */
char *result;
result = rtems_get_object_name( id, sizeof(buffer), buffer );
printk( "ID=0x%08x name=%s\n", id, ((result) ? result : "no name") );
@}
@end example
@end ifset
@subsection Object IDs
@cindex object ID

279
doc/user/rtmon.t
View File

@@ -19,9 +19,11 @@
@section Introduction
The rate monotonic manager provides facilities to
implement tasks which execute in a periodic fashion. The
directives provided by the rate monotonic manager are:
The rate monotonic manager provides facilities to implement tasks which execute
in a periodic fashion. Critically, it also gathers information about the
execution of those periods and can provide important statistics to the
user which can be used to analyze and tune the application. The directives
provided by the rate monotonic manager are:
@itemize @bullet
@item @code{@value{DIRPREFIX}rate_monotonic_create} - Create a rate monotonic period
@@ -29,7 +31,11 @@ directives provided by the rate monotonic manager are:
@item @code{@value{DIRPREFIX}rate_monotonic_cancel} - Cancel a period
@item @code{@value{DIRPREFIX}rate_monotonic_delete} - Delete a rate monotonic period
@item @code{@value{DIRPREFIX}rate_monotonic_period} - Conclude current/Start next period
@item @code{@value{DIRPREFIX}rate_monotonic_get_status} - Obtain status information on period
@item @code{@value{DIRPREFIX}rate_monotonic_get_status} - Obtain status from a period
@item @code{@value{DIRPREFIX}rate_monotonic_get_statistics} - Obtain statistics from a period
@item @code{@value{DIRPREFIX}rate_monotonic_reset_statistics} - Reset statistics for a period
@item @code{@value{DIRPREFIX}rate_monotonic_reset_all_statistics} - Reset statistics for all periods
@item @code{@value{DIRPREFIX}rate_monotonic_report_statistics} - Print period statistics report
@end itemize
@section Background
@@ -47,6 +53,78 @@ be used by any application which requires periodic tasks.
A clock tick is required to support the functionality provided by this manager.
@subsection Period Statistics
This manager maintains a set of statistics on each period. These
statistics are reset implictly at period creation time and may be
reset or obtained at any time by the application. The following
is a list of the information kept:
@itemize @bullet
@item @code{owner}
is the id of the thread that owns this 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 period statistics information is inexpensive to maintain
and can provide very useful insights into the execution
characteristics of a periodic task loop. But it is just 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.
@subsection Rate Monotonic Manager Definitions
@cindex periodic task, definition
@@ -1107,7 +1185,7 @@ This directive will not cause the running task to be preempted.
@c
@c
@page
@subsection RATE_MONOTONIC_GET_STATUS - Obtain status information on period
@subsection RATE_MONOTONIC_GET_STATUS - Obtain status from a period
@cindex get status of period
@cindex obtain status of period
@@ -1181,3 +1259,194 @@ of the @code{@value{DIRPREFIX}rate_monotonic_period} directive.
@subheading NOTES:
This directive will not cause the running task to be preempted.
@c
@c
@c
@page
@subsection RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period
@cindex get statistics of period
@cindex obtain statistics of period
@subheading CALLING SEQUENCE:
@ifset is-C
@findex rtems_rate_monotonic_get_statistics
@example
rtems_status_code rtems_rate_monotonic_get_statistics(
rtems_id id,
rtems_rate_monotonic_period_statistics *statistics
);
@end example
@end ifset
@ifset is-Ada
@example
not currently supported in Ada binding
@end example
@end ifset
@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
@code{@value{RPREFIX}INVALID_ADDRESS} - invalid address of statistics@*
@subheading DESCRIPTION:
This directive returns statistics information associated with
the rate monotonic period id in the following data @value{STRUCTURE}:
@ifset is-C
@findex rtems_rate_monotonic_period_statistics
@example
typedef struct @{
uint32_t count; /* periods executed */
uint32_t missed_count; /* period deadlines missed */
uint32_t min_cpu_time; /* minimum CPU time used in a period */
uint32_t max_cpu_time; /* maximum CPU time used in a period */
uint32_t total_cpu_time; /* total CPU time consumed */
uint32_t min_wall_time; /* minimum wall time used in a period */
uint32_t max_wall_time; /* maximum wall time used in a period */
uint32_t total_wall_time; /* total wall time consumed */
@} rtems_rate_monotonic_period_statistics;
@end example
@end ifset
@ifset is-Ada
@example
not currently supported in Ada binding
@end example
@end ifset
This directive returns the current statistics information for
the period instance assocaited with @code{id}. The information
returned is indicated by the structure above.
@subheading NOTES:
This directive will not cause the running task to be preempted.
@c
@c
@c
@page
@subsection RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period
@cindex reset statistics of period
@subheading CALLING SEQUENCE:
@ifset is-C
@findex rtems_rate_monotonic_reset_statistics
@example
rtems_status_code rtems_rate_monotonic_reset_statistics(
rtems_id id
);
@end example
@end ifset
@ifset is-Ada
@example
not currently supported in Ada binding
@end example
@end ifset
@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - period initiated successfully@*
@code{@value{RPREFIX}INVALID_ID} - invalid rate monotonic period id@*
@subheading DESCRIPTION:
This directive resets the statistics information associated with
this rate monotonic period instance.
@subheading NOTES:
This directive will not cause the running task to be preempted.
@c
@c
@c
@page
@subsection RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods
@cindex reset statistics of all periods
@subheading CALLING SEQUENCE:
@ifset is-C
@findex rtems_rate_monotonic_reset_all_statistics
@example
void rtems_rate_monotonic_reset_all_statistics(void);
@end example
@end ifset
@ifset is-Ada
@example
not currently supported in Ada binding
@end example
@end ifset
@subheading DIRECTIVE STATUS CODES:
NONE
@subheading DESCRIPTION:
This directive resets the statistics information associated with
all rate monotonic period instances.
@subheading NOTES:
This directive will not cause the running task to be preempted.
@c
@c
@c
@page
@subsection RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report
@cindex print period statistics report
@cindex period statistics report
@subheading CALLING SEQUENCE:
@ifset is-C
@findex rtems_rate_monotonic_report_statistics
@example
void rtems_rate_monotonic_report_statistics(void);
@end example
@end ifset
@ifset is-Ada
@example
not currently supported in Ada binding
@end example
@end ifset
@subheading DIRECTIVE STATUS CODES:
NONE
@subheading DESCRIPTION:
This directive prints a report on all active periods which have
executed at least one period. The following is an example of the
output generated by this directive.
@ifset is-C
@findex rtems_rate_monotonic_period_statistics
@example
ID OWNER PERIODS MISSED CPU TIME WALL TIME
0x42010001 TA1 502 0 0/1/0.99 0/0/0.00
0x42010002 TA2 502 0 0/1/0.99 0/0/0.00
0x42010003 TA3 501 0 0/1/0.99 0/0/0.00
0x42010004 TA4 501 0 0/1/0.99 0/0/0.00
0x42010005 TA5 10 0 0/1/0.90 0/0/0.00
@end example
@end ifset
@subheading NOTES:
This directive will not cause the running task to be preempted.