summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>1998-11-19 16:05:05 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>1998-11-19 16:05:05 +0000
commitd82f3e81a4ebfef1fbe471936339ba9260bfcc98 (patch)
treedf2ea5f1c76c748b9852a94cc1403ed5c8f22fd7
parentbc950e878a06243e272493eff8a9509b4e416483 (diff)
downloadrtems-d82f3e81a4ebfef1fbe471936339ba9260bfcc98.tar.bz2
New files
-rw-r--r--doc/new_chapters/TODO4
-rw-r--r--doc/new_chapters/cpuuse.t142
-rw-r--r--doc/new_chapters/error.t164
-rw-r--r--doc/new_chapters/monitor.t224
-rw-r--r--doc/new_chapters/rtmonuse.t294
-rw-r--r--doc/new_chapters/stackchk.t192
6 files changed, 1020 insertions, 0 deletions
diff --git a/doc/new_chapters/TODO b/doc/new_chapters/TODO
new file mode 100644
index 0000000000..9f5a884add
--- /dev/null
+++ b/doc/new_chapters/TODO
@@ -0,0 +1,4 @@
+
+General - check that all nodes have "none" if they don't have a note.
+
+
diff --git a/doc/new_chapters/cpuuse.t b/doc/new_chapters/cpuuse.t
new file mode 100644
index 0000000000..ccb92883b8
--- /dev/null
+++ b/doc/new_chapters/cpuuse.t
@@ -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
diff --git a/doc/new_chapters/error.t b/doc/new_chapters/error.t
new file mode 100644
index 0000000000..fe708800bd
--- /dev/null
+++ b/doc/new_chapters/error.t
@@ -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
+
diff --git a/doc/new_chapters/monitor.t b/doc/new_chapters/monitor.t
new file mode 100644
index 0000000000..c15805723c
--- /dev/null
+++ b/doc/new_chapters/monitor.t
@@ -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.
+
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
diff --git a/doc/new_chapters/stackchk.t b/doc/new_chapters/stackchk.t
new file mode 100644
index 0000000000..55f39433a6
--- /dev/null
+++ b/doc/new_chapters/stackchk.t
@@ -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