forked from Imagelibrary/rtems
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.
This commit is contained in:
Joel Sherrill
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user