2007-05-11 Joel Sherrill <joel.sherrill@OARcorp.com>

	* user/.cvsignore, user/cpuuse.t, user/stackchk.t: Stack checker and
	CPU usage chapters are now OK in the manual.

4 files changed, 83 insertions, 29 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 66df517bfa..a7081b3b49 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2007-05-11	Joel Sherrill <joel.sherrill@OARcorp.com>
+
+	* user/.cvsignore, user/cpuuse.t, user/stackchk.t: Stack checker and
+	CPU usage chapters are now OK in the manual.
+
 2007-05-09	Ralf Corsépius <ralf.corsepius@rtems.org>
 
 	* porting/miscellaneous.t: Remove subsection on "Optional
diff --git a/doc/user/.cvsignore b/doc/user/.cvsignore
index bbf7de1754..79dc66fa4b 100644
--- a/doc/user/.cvsignore
+++ b/doc/user/.cvsignore
@@ -1,3 +1,4 @@
+barrier.texi
 bsp.texi
 clock.texi
 concepts.texi
diff --git a/doc/user/cpuuse.t b/doc/user/cpuuse.t
index 161df741cd..4c67c58432 100644
--- a/doc/user/cpuuse.t
+++ b/doc/user/cpuuse.t
@@ -1,5 +1,5 @@
 @c
-@c  COPYRIGHT (c) 1988-2002.
+@c  COPYRIGHT (c) 1988-2007.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved. 
 @c
@@ -22,11 +22,28 @@ The routines provided by the CPU usage statistics manager are:
 
 @section Background
 
-@section Operations
+When analyzing and debugging real-time applications, it is important
+to be able to know how much CPU time each task in the system consumes.
+This support component provides a mechanism to easily obtain this
+information with little burden placed on the target.
+
+The raw data is gathered as part of performing a context switch.  RTEMS
+keeps track of how many clock ticks have occurred which the task being
+switched out has been executing.  If the task has been running less than
+1 clock tick, then for the purposes of the statistics, it is assumed to
+have executed 1 clock tick.  This results in some inaccuracy but the
+alternative is for the task to have appeared to execute 0 clock ticks.
+
+RTEMS versions newer than the 4.7 release series, support the ability
+to obtain timestamps with nanosecond granularity if the BSP provides
+support.  It is a desirable enhancement to change the way the usage
+data is gathered to take advantage of this recently added capability.
+Please consider sponsoring the core RTEMS development team to add
+this capability.
 
-@section Report CPU Usage Statistics
+@section Operations
 
-@subsection Reporting Period Statistics
+@subsection Report CPU Usage Statistics
 
 The application may dynamically report the CPU usage for every
 task in the system by calling the
@@ -72,7 +89,7 @@ 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
+@subsection Reset CPU Usage Statistics
 
 Invoking the @code{@value{DIRPREFIX}cpu_usage_reset} routine resets
 the CPU usage statistics for all tasks in the system. 
@@ -110,7 +127,7 @@ all tasks in the system.
 
 @subheading NOTES:
 
-NONE
+The table is printed using the @code{printk} routine.
 
 @page
 @subsection cpu_usage_reset - Reset CPU Usage Statistics
diff --git a/doc/user/stackchk.t b/doc/user/stackchk.t
index 0d975265e6..64e529de9e 100644
--- a/doc/user/stackchk.t
+++ b/doc/user/stackchk.t
@@ -1,5 +1,5 @@
 @c
-@c  COPYRIGHT (c) 1988-2006.
+@c  COPYRIGHT (c) 1988-2007.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved. 
 @c
@@ -11,11 +11,11 @@
 @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
+if a task has overrun 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_is_blown} - Has the Current Task Blown its Stack
 @item @code{@value{DIRPREFIX}stack_checker_report_usage} - Report Task Stack Usage
 @end itemize
 
@@ -35,8 +35,8 @@ 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.
+of stack space.  If the routine recursives 1000 times, then
+@code{1000 * @i{n}} bytes of stack space are required.
 
 @subsection Execution
 
@@ -44,9 +44,22 @@ 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.
+task switch extension is executed.  This extension checks that:
+
+@itemize @bullet
+
+@item the last @code{n} bytes of the task's stack have
+not been overwritten.  If this pattern has been damaged, it
+indicates that at some point since this task was context
+switch to the CPU, it has used too much stack space.
+
+@item the current stack pointer of the task is not within
+the address range allocated for use as the task's stack.
+
+@end itemize
+
+If either of these conditions is detected, then a blown stack
+error is reported using the @code{printk} routine.
 
 The number of bytes checked for an overwrite is processor family dependent.
 The minimum stack frame per subroutine call varies widely between processor
@@ -67,28 +80,36 @@ provided by every RTEMS port to get for this information.
 @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.
+create extension runs for the first time.
 
 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>}
+defined as @code{STACK_CHECKER_EXTENSION}.  If using @code{<rtems/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:
+@code{<rtems/confdefs.h>} as shown below:
 
 @example
 @group
 #define STACK_CHECKER_ON
   ...
-#include <confdefs.h>
+#include <rtems/confdefs.h>
 @end group
 @end example
 
+@subsection Checking for Blown Task Stack
+
+The application may check whether the stack pointer of currently
+executing task is within proper bounds at any time by calling
+the @code{@value{DIRPREFIX}stack_checker_is_blown} method.  This
+method return @code{FALSE} if the task is operating within its 
+stack bounds and has not damaged its pattern area.
+
 @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_report_usage} routine.
+in the system by calling the
+@code{@value{DIRPREFIX}stack_checker_report_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:
@@ -110,9 +131,9 @@ 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.
+it will attempt to print a message using @code{printk} 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:
 
@@ -135,14 +156,18 @@ A subsection is dedicated to each of routines
 and describes the calling sequence, related constants, usage,
 and status codes.
 
+
+@c
+@c  rtems_stack_checker_is_blown
+@c
 @page
-@subsection stack_checker_initialize - Initialize the Stack Bounds Checker
+@subsection stack_checker_is_blown - Has Current Task Blown Its Stack
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
-void rtems_stack_checker_initialize( void );
+boolean rtems_stack_checker_is_blown( void );
 @end example
 @end ifset
 
@@ -152,16 +177,22 @@ An Ada interface is not currently available.
 @end example
 @end ifset
 
-@subheading STATUS CODES: NONE
+@subheading STATUS CODES:
+@code{TRUE} - Stack is operating within its stack limits@*
+@code{FALSE} - Current stack pointer is outside allocated area 
+
 
 @subheading DESCRIPTION:
 
-Initialize the stack bounds checker.
+This method is used to determine if the current stack pointer
+of the currently executing task is within bounds.
 
 @subheading NOTES:
 
-This is performed automatically the first time the stack bounds checker
-task create extension executes.
+This method checks the current stack pointer against
+the high and low addresses of the stack memory allocated when
+the task was created and it looks for damage to the high water
+mark pattern for the worst case usage of the task being called.
 
 @page
 @subsection stack_checker_report_usage - Report Task Stack Usage