From d82f3e81a4ebfef1fbe471936339ba9260bfcc98 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Thu, 19 Nov 1998 16:05:05 +0000 Subject: New files --- doc/new_chapters/TODO | 4 + doc/new_chapters/cpuuse.t | 142 +++++++++++++++++++++ doc/new_chapters/error.t | 164 ++++++++++++++++++++++++ doc/new_chapters/monitor.t | 224 +++++++++++++++++++++++++++++++++ doc/new_chapters/rtmonuse.t | 294 ++++++++++++++++++++++++++++++++++++++++++++ doc/new_chapters/stackchk.t | 192 +++++++++++++++++++++++++++++ 6 files changed, 1020 insertions(+) create mode 100644 doc/new_chapters/TODO create mode 100644 doc/new_chapters/cpuuse.t create mode 100644 doc/new_chapters/error.t create mode 100644 doc/new_chapters/monitor.t create mode 100644 doc/new_chapters/rtmonuse.t create mode 100644 doc/new_chapters/stackchk.t (limited to 'doc') 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_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{} +for Configuration Table generation, then all that is necessary is +to define the macro @code{STACK_CHECKER_ON} before including +@code{} as shown below: + +@example +@group +#define STACK_CHECKER_ON + ... +#include +@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 -- cgit v1.2.3