forked from Imagelibrary/rtems
New files
This commit is contained in:
Joel Sherrill
4
doc/new_chapters/TODO
Normal file
4
doc/new_chapters/TODO
Normal file
@@ -0,0 +1,4 @@
|
||||
|
||||
General - check that all nodes have "none" if they don't have a note.
|
||||
|
||||
|
||||
142
doc/new_chapters/cpuuse.t
Normal file
142
doc/new_chapters/cpuuse.t
Normal file
@@ -0,0 +1,142 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-1998.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
@c
|
||||
@c $Id$
|
||||
@c
|
||||
|
||||
@chapter CPU Usage Statistics
|
||||
|
||||
@section Introduction
|
||||
|
||||
The CPU usage statistics manager is an RTEMS support
|
||||
component that provides a convenient way to manipulate
|
||||
the CPU usage information associated with each task
|
||||
The routines provided by the CPU usage statistics manager are:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{CPU_usage_Dump} - Report CPU Usage Statistics
|
||||
@item @code{CPU_usage_Reset} - Reset CPU Usage Statistics
|
||||
@end itemize
|
||||
|
||||
@section Background
|
||||
|
||||
@section Operations
|
||||
|
||||
@section Report CPU Usage Statistics
|
||||
|
||||
@subsection Reporting Period Statistics
|
||||
|
||||
The application may dynamically report the CPU usage for every
|
||||
task in the system by calling the @code{CPU_usage_Dump} routine.
|
||||
This routine prints a table with the following information per task:
|
||||
|
||||
@itemize @bullet
|
||||
@item task id
|
||||
@item task name
|
||||
@item number of clock ticks executed
|
||||
@item percentage of time consumed by this task
|
||||
@end itemize
|
||||
|
||||
The following is an example of the report generated:
|
||||
|
||||
@example
|
||||
@group
|
||||
CPU Usage by thread
|
||||
ID NAME TICKS PERCENT
|
||||
0x04010001 IDLE 0 0.000
|
||||
0x08010002 TA1 1203 0.748
|
||||
0x08010003 TA2 203 0.126
|
||||
0x08010004 TA3 202 0.126
|
||||
|
||||
Ticks since last reset = 1600
|
||||
|
||||
Total Units = 1608
|
||||
@end group
|
||||
@end example
|
||||
|
||||
Notice that the "Total Units" is greater than the ticks per reset.
|
||||
This is an artifact of the way in which RTEMS keeps track of CPU
|
||||
usage. When a task is context switched into the CPU, the number
|
||||
of clock ticks it has executed is incremented. While the task
|
||||
is executing, this number is incremented on each clock tick.
|
||||
Otherwise, if a task begins and completes execution between
|
||||
successive clock ticks, there would be no way to tell that it
|
||||
executed at all.
|
||||
|
||||
Another thing to keep in mind when looking at idle time, is that
|
||||
many systems -- especially during debug -- have a task providing
|
||||
some type of debug interface. It is usually fine to think of the
|
||||
total idle time as being the sum of the IDLE task and a debug
|
||||
task that will not be included in a production build of an application.
|
||||
|
||||
@section Reset CPU Usage Statistics
|
||||
|
||||
Invoking the @code{CPU_usage_Reset} routine resets the CPU usage
|
||||
statistics for all tasks in the system.
|
||||
|
||||
@section Directives
|
||||
|
||||
This section details the CPU usage statistics manager's directives.
|
||||
A subsection is dedicated to each of this manager's directives
|
||||
and describes the calling sequence, related constants, usage,
|
||||
and status codes.
|
||||
|
||||
@page
|
||||
@subsection CPU_usage_Dump - Report CPU Usage Statistics
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
void CPU_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 CPU usage statistics for
|
||||
all tasks in the system.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
NONE
|
||||
|
||||
@page
|
||||
@subsection CPU_usage_Reset - Reset CPU Usage Statistics
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
void CPU_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 CPU usage statistics for all tasks
|
||||
in the system to their initial state. The initial state is that
|
||||
a task has not executed and thus has consumed no CPU time.
|
||||
default state which is when zero period executions have occurred.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
NONE
|
||||
164
doc/new_chapters/error.t
Normal file
164
doc/new_chapters/error.t
Normal file
@@ -0,0 +1,164 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-1998.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
@c
|
||||
@c $Id$
|
||||
@c
|
||||
|
||||
@chapter Error Reporting Support
|
||||
|
||||
@section Introduction
|
||||
|
||||
These error reporting facilities are an RTEMS support
|
||||
component that provide convenient facilities for handling
|
||||
error conditions in an RTEMS application.
|
||||
of each task using a period. The services provided by the error
|
||||
reporting support component are:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{rtems_error} - Report an Error
|
||||
@item @code{rtems_panic} - Report an Error and Panic
|
||||
@item @code{rtems_status_text} - ASCII Version of RTEMS Status
|
||||
@end itemize
|
||||
|
||||
@section Background
|
||||
|
||||
@subsection Error Handling in an Embedded System
|
||||
|
||||
Error handling in an embedded system is a difficult problem. If the error
|
||||
is severe, then the only recourse is to shut the system down in a safe
|
||||
manner. Other errors can be detected and compensated for. The
|
||||
error reporting routines in this support component -- @code{rtems_error}
|
||||
and @code{rtems_panic} assume that if the error is severe enough,
|
||||
then the system should be shutdown. If a simple shutdown with
|
||||
some basic diagnostic information is not sufficient, then
|
||||
these routines should not be used in that particular system. In this case,
|
||||
use the @code{rtems_status_text} routine to construct an application
|
||||
specific error reporting routine.
|
||||
|
||||
@section Operations
|
||||
|
||||
@subsection Reporting an Error
|
||||
|
||||
The @code{rtems_error} and @code{rtems_panic} routines
|
||||
can be used to print some diagnostic information and
|
||||
shut the system down. The @code{rtems_error} routine
|
||||
is invoked with a user specified error level indicator.
|
||||
This error indicator is used to determine if the system
|
||||
should be shutdown after reporting this error.
|
||||
|
||||
@section Routines
|
||||
|
||||
This section details the error reporting support compenent's routine.
|
||||
A subsection is dedicated to each of this manager's routines
|
||||
and describes the calling sequence, related constants, usage,
|
||||
and status codes.
|
||||
|
||||
@page
|
||||
@subsection rtems_status_text - ASCII Version of RTEMS Status
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
const char *rtems_status_text(
|
||||
rtems_status_code status
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@example
|
||||
An Ada interface is not currently available.
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
Returns a pointer to a constant string that describes the given
|
||||
RTEMS status code.
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
This routine returns a pointer to a string that describes
|
||||
the RTEMS status code specified by @code{status}.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
NONE
|
||||
|
||||
@page
|
||||
@subsection rtems_error - Report an Error
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
int rtems_error(
|
||||
int error_code,
|
||||
const char *printf_format,
|
||||
...
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@example
|
||||
An Ada interface is not currently available.
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
Returns the number of characters written.
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
This routine prints the requested information as specified by the
|
||||
@code{printf_format} parameter and the zero or more optional arguments
|
||||
following that parameter. The @code{error_code} parameter is an error
|
||||
number with either @code{RTEMS_ERROR_PANIC} or @code{RTEMS_ERROR_ABORT}
|
||||
bitwise or'ed with it. If the @code{RTEMS_ERROR_PANIC} bit is set, then
|
||||
then the system is system is shutdown via a call to @code{_exit}.
|
||||
If the @code{RTEMS_ERROR_ABORT} bit is set, then
|
||||
then the system is system is shutdown via a call to @code{abort}.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
NONE
|
||||
|
||||
@page
|
||||
@subsection rtems_panic - Report an Error and Panic
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
int rtems_panic(
|
||||
const char *printf_format,
|
||||
...
|
||||
);
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset is-Ada
|
||||
@example
|
||||
An Ada interface is not currently available.
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@subheading STATUS CODES:
|
||||
|
||||
Returns the number of characters written.
|
||||
|
||||
@subheading DESCRIPTION:
|
||||
|
||||
This routine is a wrapper for the @code{rtems_error} routine with
|
||||
an implied error level of @code{RTEMS_ERROR_PANIC}. See
|
||||
@code{rtems_error} for more information.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
NONE
|
||||
|
||||
224
doc/new_chapters/monitor.t
Normal file
224
doc/new_chapters/monitor.t
Normal file
@@ -0,0 +1,224 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-1998.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
@c
|
||||
@c $Id$
|
||||
@c
|
||||
|
||||
@chapter Monitor Task
|
||||
|
||||
@section Introduction
|
||||
|
||||
The monitor task is a simple interactive shell that allows the user to
|
||||
make inquries about he state of various system objects. The routines
|
||||
provided by the monitor task manager are:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{rtems_monitor_init} - Initialize the Monitor Task
|
||||
@item @code{rtems_monitor_wakeup} - Wakeup the Monitor Task
|
||||
@end itemize
|
||||
|
||||
@section Background
|
||||
|
||||
There is no background information.
|
||||
|
||||
@section Operations
|
||||
|
||||
@subsection Initializing the Monitor
|
||||
|
||||
The monitor is initialized by calling @code{rtems_monitor_init}. When
|
||||
initialized, the monitor is created as an independent task. An example
|
||||
of initializing the monitor is shown below:
|
||||
|
||||
@example
|
||||
@group
|
||||
#include <rtems/monitor.h>
|
||||
...
|
||||
rtems_monitor_init(0);
|
||||
@end group
|
||||
@end example
|
||||
|
||||
The "0" parameter to the @code{rtems_monitor_init} routine
|
||||
causes the monitor to immediately enter command mode.
|
||||
This parameter is a bitfield. If the monitor is to suspend
|
||||
itself on startup, then the @code{RTEMS_MONITOR_SUSPEND} bit
|
||||
should be set.
|
||||
|
||||
@section Routines
|
||||
|
||||
This section details the monitor task 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 rtems_monitor_init - Initialize the Monitor Task
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
void rtems_monitor_init(
|
||||
unsigned32 monitor_flags
|
||||
);
|
||||
@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 initializes the RTEMS monitor task. The
|
||||
@code{monitor_flags} parameter indicates how the server
|
||||
task is to start. This parameter is a bitfield and
|
||||
has the following constants associated with it:
|
||||
|
||||
@itemize @bullet
|
||||
@item @b{RTEMS_MONITOR_SUSPEND} - suspend monitor on startup
|
||||
@item @b{RTEMS_MONITOR_GLOBAL} - monitor should be global
|
||||
@end itemize
|
||||
|
||||
If the @code{RTEMS_MONITOR_SUSPEND} bit is set, then the
|
||||
monitor task will suspend itself after it is initialized.
|
||||
A subsequent call to @code{rtems_monitor_wakeup} will be required
|
||||
to activate it.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
The monitor task is created with priority 1. If there are
|
||||
application tasks at priority 1, then there may be times
|
||||
when the monitor task is not executing.
|
||||
|
||||
@page
|
||||
@subsection rtems_monitor_wakeup - Wakeup the Monitor Task
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
void rtems_monitor_wakeup( 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 is used to activate the monitor task if it is suspended.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
NONE
|
||||
|
||||
@page
|
||||
@section Monitor Interactive Commands
|
||||
|
||||
The following commands are supported by the monitor task:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{help} - Obtain Help
|
||||
@item @code{pause} - Pause Monitor for a Specified Number of Ticks
|
||||
@item @code{exit} - Invoke a Fatal RTEMS Error
|
||||
@item @code{symbol} - Show Entries from Symbol Table
|
||||
@item @code{continue} - Put Monitor to Sleep Waiting for Explicit Wakeup
|
||||
@item @code{config} - Show System Configuration
|
||||
@item @code{itask} - List Init Tasks
|
||||
@item @code{mpci} - List MPCI Config
|
||||
@item @code{task} - Show Task Information
|
||||
@item @code{queue} - Show Message Queue Information
|
||||
@item @code{extension} - User Extensions
|
||||
@item @code{driver} - Show Information About Named Drivers
|
||||
@item @code{dname} - Show Information About Named Drivers
|
||||
@item @code{object} - Generic Object Information
|
||||
@item @code{node} - Specify Default Node for Commands That Take IDs
|
||||
@end itemize
|
||||
|
||||
|
||||
@subsection help - Obtain Help
|
||||
|
||||
The @code{help} command prints out the list of commands. If invoked
|
||||
with a command name as the first argument, detailed help information
|
||||
on that command is printed.
|
||||
|
||||
@subsection pause - Pause Monitor for a Specified Number of Ticks
|
||||
|
||||
The @code{pause} command cause the monitor task to suspend itself
|
||||
for the specified number of ticks. If this command is invoked with
|
||||
no arguments, then the task is suspended for 1 clock tick.
|
||||
|
||||
@subsection exit - Invoke a Fatal RTEMS Error
|
||||
|
||||
The @code{exit} command invokes @code{rtems_error_occurred} directive
|
||||
with the specified error code. If this command is invoked with
|
||||
no arguments, then the @code{rtems_error_occurred} directive is
|
||||
invoked with an arbitrary error code.
|
||||
|
||||
@subsection symbol - Show Entries from Symbol Table
|
||||
|
||||
The @code{symbol} command lists the specified entries in the symbol table.
|
||||
If this command is invoked with no arguments, then all the
|
||||
symbols in the symbol table are printed.
|
||||
|
||||
@subsection continue - Put Monitor to Sleep Waiting for Explicit Wakeup
|
||||
|
||||
The @code{continue} command suspends the monitor task with no timeout.
|
||||
|
||||
@subsection config - Show System Configuration
|
||||
|
||||
The @code{config} command prints the system configuration.
|
||||
|
||||
@subsection itask - List Init Tasks
|
||||
|
||||
The @code{itask} command lists the tasks in the initialization tasks table.
|
||||
|
||||
@subsection mpci - List MPCI Config
|
||||
|
||||
The @code{mpci} command shows the MPCI configuration information
|
||||
|
||||
@subsection task - Show Task Information
|
||||
|
||||
The @code{task} command prints out information about one or more tasks in
|
||||
the system. If invoked with no arguments, then
|
||||
information on all the tasks in the system is printed.
|
||||
|
||||
@subsection queue - Show Message Queue Information
|
||||
|
||||
The @code{queue} command prints out information about one or more
|
||||
message queues in the system. If invoked with no arguments, then
|
||||
information on all the message queues in the system is printed.
|
||||
|
||||
@subsection extension - User Extensions
|
||||
|
||||
The @code{extension} command prints out information about the user
|
||||
extensions.
|
||||
|
||||
@subsection driver - Show Information About Named Drivers
|
||||
|
||||
The @code{driver} command prints information about the device driver table.
|
||||
|
||||
@subsection dname - Show Information About Named Drivers
|
||||
|
||||
The @code{dname} command prints information about the named device drivers.
|
||||
|
||||
@subsection object - Generic Object Information
|
||||
|
||||
The @code{object} command prints information about RTEMS objects.
|
||||
|
||||
@subsection node - Specify Default Node for Commands That Take IDs
|
||||
|
||||
The @code{node} command sets the default node for commands that look
|
||||
at object ID ranges.
|
||||
|
||||
294
doc/new_chapters/rtmonuse.t
Normal file
294
doc/new_chapters/rtmonuse.t
Normal file
@@ -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
|
||||
192
doc/new_chapters/stackchk.t
Normal file
192
doc/new_chapters/stackchk.t
Normal file
@@ -0,0 +1,192 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-1998.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
@c
|
||||
@c $Id$
|
||||
@c
|
||||
|
||||
@chapter Stack Bounds Checker
|
||||
|
||||
@section Introduction
|
||||
|
||||
The stack bounds checker is an RTEMS support component that determines
|
||||
if a task has overflowed its run-time stack. The routines provided
|
||||
by the stack bounds checker manager are:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{Stack_check_Initialize} - Initialize the Stack Bounds Checker
|
||||
@item @code{Stack_check_Dump_usage} - Report Task Stack Usage
|
||||
@end itemize
|
||||
|
||||
@section Background
|
||||
|
||||
@subsection Task Stack
|
||||
|
||||
Each task in a system has a fixed size stack associated with it. This
|
||||
stack is allocated when the task is created. As the task executes, the
|
||||
stack is used to contain parameters, return addresses, saved registers,
|
||||
and local variables. The amount of stack space required by a task
|
||||
is dependent on the exact set of routines used. The peak stack usage
|
||||
reflects the worst case of subroutine pushing information on the stack.
|
||||
For example, if a subroutine allocates a local buffer of 1024 bytes, then
|
||||
this data must be accounted for in the stack of every task that invokes that
|
||||
routine.
|
||||
|
||||
Recursive routines make calculating peak stack usage difficult, if not
|
||||
impossible. Each call to the recursive routine consumes @i{n} bytes
|
||||
of stack space. If the routine recursives 1000 times, then @code{1000 * @i{n}}
|
||||
bytes of stack space are required.
|
||||
|
||||
@subsection Execution
|
||||
|
||||
The stack bounds checker operates as a set of task extensions. At
|
||||
task creation time, the task's stack is filled with a pattern to
|
||||
indicate the stack is unused. As the task executes, it will overwrite
|
||||
this pattern in memory. At each task switch, the stack bounds checker's
|
||||
task switch extension is executed. This extension checks that the last
|
||||
@code{n} bytes of the task's stack have not been overwritten. If they
|
||||
have, then a blown stack error is reported.
|
||||
|
||||
The number of bytes checked for an overwrite is processor family dependent.
|
||||
The minimum stack frame per subroutine call varies widely between processor
|
||||
families. On CISC families like the Motorola MC68xxx and Intel ix86, all
|
||||
that is needed is a return address. On more complex RISC processors,
|
||||
the minimum stack frame per subroutine call may include space to save
|
||||
a significant number of registers.
|
||||
|
||||
Another processor dependent feature that must be taken into account by
|
||||
the stack bounds checker is the direction that the stack grows. On some
|
||||
processor families, the stack grows up or to higher addresses as the
|
||||
task executes. On other families, it grows down to lower addresses. The
|
||||
stack bounds checker implementation uses the stack description definitions
|
||||
provided by every RTEMS port to get for this information.
|
||||
|
||||
@section Operations
|
||||
|
||||
@subsection Initializing the Stack Bounds Checker
|
||||
|
||||
The stack checker is initialized automatically when its task
|
||||
create extension runs for the first time. When this occurs,
|
||||
the @code{Stack_check_Initialize} is invoked.
|
||||
|
||||
The application must include the stack bounds checker extension set
|
||||
in its set of Initial Extensions. This set of extensions is
|
||||
defined as @code{STACK_CHECKER_EXTENSION}. If using @code{<confdefs.h>}
|
||||
for Configuration Table generation, then all that is necessary is
|
||||
to define the macro @code{STACK_CHECKER_ON} before including
|
||||
@code{<confdefs.h>} as shown below:
|
||||
|
||||
@example
|
||||
@group
|
||||
#define STACK_CHECKER_ON
|
||||
...
|
||||
#include <confdefs.h>
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Reporting Task Stack Usage
|
||||
|
||||
The application may dynamically report the stack usage for every task
|
||||
in the system by calling the @code{Stack_check_Dump_usage} routine.
|
||||
This routine prints a table with the peak usage and stack size of
|
||||
every task in the system. The following is an example of the
|
||||
report generated:
|
||||
|
||||
@example
|
||||
@group
|
||||
ID NAME LOW HIGH AVAILABLE USED
|
||||
0x04010001 IDLE 0x003e8a60 0x003e9667 2952 200
|
||||
0x08010002 TA1 0x003e5750 0x003e7b57 9096 1168
|
||||
0x08010003 TA2 0x003e31c8 0x003e55cf 9096 1168
|
||||
0x08010004 TA3 0x003e0c40 0x003e3047 9096 1104
|
||||
0xffffffff INTR 0x003ecfc0 0x003effbf 12160 128
|
||||
@end group
|
||||
@end example
|
||||
|
||||
Notice the last time. The task id is 0xffffffff and its name is "INTR".
|
||||
This is not actually a task, it is the interrupt stack.
|
||||
|
||||
@subsection When a Task Overflows the Stack
|
||||
|
||||
When the stack bounds checker determines that a stack overflow has occurred,
|
||||
it will attempt to print a message identifying the task and then shut the
|
||||
system down. If the stack overflow has caused corruption, then it is
|
||||
possible that the message can not be printed.
|
||||
|
||||
The following is an example of the output generated:
|
||||
|
||||
@example
|
||||
@group
|
||||
BLOWN STACK!!! Offending task(0x3eb360): id=0x08010002; name=0x54413120
|
||||
stack covers range 0x003e5750 - 0x003e7b57 (9224 bytes)
|
||||
Damaged pattern begins at 0x003e5758 and is 128 bytes long
|
||||
@end group
|
||||
@end example
|
||||
|
||||
The above includes the task id and a pointer to the task control block as
|
||||
well as enough information so one can look at the task's stack and
|
||||
see what was happening.
|
||||
|
||||
@section Routines
|
||||
|
||||
This section details the stack bounds checker's routines.
|
||||
A subsection is dedicated to each of routines
|
||||
and describes the calling sequence, related constants, usage,
|
||||
and status codes.
|
||||
|
||||
@page
|
||||
@subsection Stack_check_Initialize - Initialize the Stack Bounds Checker
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
void Stack_check_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:
|
||||
|
||||
Initialize the stack bounds checker.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
This is performed automatically the first time the stack bounds checker
|
||||
task create extension executes.
|
||||
|
||||
@page
|
||||
@subsection Stack_check_Dump_usage - Report Task Stack Usage
|
||||
|
||||
@subheading CALLING SEQUENCE:
|
||||
|
||||
@ifset is-C
|
||||
@example
|
||||
void Stack_check_Dump_usage( 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 a table with the peak stack usage and stack space
|
||||
allocation of every task in the system.
|
||||
|
||||
@subheading NOTES:
|
||||
|
||||
NONE
|
||||
Reference in New Issue
Block a user