2006-09-13 Joel Sherrill <joel@OARcorp.com>

	* new_chapters/Makefile.am, user/Makefile.am, user/c_user.texi,
	user/dirstat.texi, user/task.t: Move stack to first class citizen
	status. Include it in User Manual and rename to start with rtems_.
	* user/stackchk.t: New file.
	* new_chapters/stackchk.t: Removed.

5 files changed, 207 insertions, 7 deletions

diff --git a/doc/user/Makefile.am b/doc/user/Makefile.am
index 90182f51b4..8aaf34c041 100644
--- a/doc/user/Makefile.am
+++ b/doc/user/Makefile.am
@@ -17,7 +17,8 @@ FILES = bsp.texi dirstat.texi example.texi glossary.texi preface.texi
 GENERATED_FILES = overview.texi concepts.texi datatypes.texi init.texi \
     task.texi intr.texi clock.texi timer.texi sem.texi msg.texi event.texi \
     signal.texi part.texi region.texi dpmem.texi io.texi fatal.texi \
-    schedule.texi rtmon.texi bsp.texi userext.texi conf.texi mp.texi
+    schedule.texi rtmon.texi bsp.texi userext.texi conf.texi mp.texi \
+    stackchk.texi
 
 COMMON_FILES += $(top_srcdir)/common/cpright.texi
 
@@ -156,11 +157,16 @@ conf.texi: conf.t
 mp.texi: mp.t
 	$(BMENU2) -p "Configuring a System Sizing the RTEMS RAM Workspace" \
 	    -u "Top" \
+	    -n "Stack Bounds Checker" < $< > $@
+
+stackchk.texi: stackchk.t
+	$(BMENU2) -p "Multiprocessing Manager MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet" \
+	    -u "Top" \
 	    -n "Directive Status Codes" < $< > $@
 
 EXTRA_DIST = bsp.t concepts.t clock.t datatypes.t conf.t dpmem.t event.t \
     fatal.t init.t intr.t io.t mp.t msg.t overview.t part.t region.t rtmon.t \
-    sem.t schedule.t signal.t task.t timer.t userext.t $(TXT_FILES) $(PNG_FILES) \
-    $(EPS_IMAGES) $(noinst_DATA)
+    sem.t schedule.t signal.t stackchk.t task.t timer.t userext.t \
+    $(TXT_FILES) $(PNG_FILES) $(EPS_IMAGES) $(noinst_DATA)
 
 CLEANFILES += c_user.info c_user.info-? c_user.info-??
diff --git a/doc/user/c_user.texi b/doc/user/c_user.texi
index 4ade92d03d..3336c1dae5 100644
--- a/doc/user/c_user.texi
+++ b/doc/user/c_user.texi
@@ -7,7 +7,7 @@
 @c %**end of header
 
 @c
-@c  COPYRIGHT (c) 1988-2002.
+@c  COPYRIGHT (c) 1988-2006.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 @c
@@ -100,6 +100,7 @@
 @include userext.texi
 @include conf.texi
 @include mp.texi
+@include stackchk.texi
 @include dirstat.texi
 @include example.texi
 @include glossary.texi
@@ -134,6 +135,7 @@ This is the online version of the RTEMS C User's Guide.
 * User Extensions Manager::
 * Configuring a System::
 * Multiprocessing Manager::
+* Stack Bounds Checker::
 * Directive Status Codes::
 * Example Application::
 * Glossary::
diff --git a/doc/user/dirstat.texi b/doc/user/dirstat.texi
index 094bcf2b13..e7576e40e6 100644
--- a/doc/user/dirstat.texi
+++ b/doc/user/dirstat.texi
@@ -1,5 +1,5 @@
 @c
-@c  COPYRIGHT (c) 1988-2002.
+@c  COPYRIGHT (c) 1988-2006.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 @c
@@ -7,7 +7,7 @@
 @c
 
 @ifinfo
-@node Directive Status Codes, Example Application, Multiprocessing Manager MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet, Top
+@node Directive Status Codes, Example Application, Stack Bounds Checker stack_checker_dump_usage - Report Task Stack Usage, Top
 @end ifinfo
 @chapter Directive Status Codes
 @table @b
diff --git a/doc/user/stackchk.t b/doc/user/stackchk.t
new file mode 100644
index 0000000000..00cde1b386
--- /dev/null
+++ b/doc/user/stackchk.t
@@ -0,0 +1,192 @@
+@c
+@c  COPYRIGHT (c) 1988-2006.
+@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{@value{DIRPREFIX}stack_checker_initialize} - Initialize the Stack Bounds Checker
+@item @code{@value{DIRPREFIX}stack_checker_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{@value{DIRPREFIX}stack_checker_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{@value{DIRPREFIX}stack_checker_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_checker_initialize - Initialize the Stack Bounds Checker
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+void rtems_stack_checker_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_checker_dump_usage - Report Task Stack Usage
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+void rtems_stack_checker_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
diff --git a/doc/user/task.t b/doc/user/task.t
index 115536eb22..8ad87d0760 100644
--- a/doc/user/task.t
+++ b/doc/user/task.t
@@ -1,5 +1,5 @@
 @c
-@c  COPYRIGHT (c) 1988-2002.
+@c  COPYRIGHT (c) 1988-2006.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 @c