source: rtems/doc/user/stackchk.t @ d5671b1

4.104.114.9
Last change on this file since d5671b1 was d5671b1, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 29, 2008 at 9:37:00 PM

2008-01-29 Joel Sherrill <joel.sherrill@…>

  • user/.cvsignore, user/Makefile.am, user/c_user.texi, user/concepts.t, user/conf.t, user/dirstat.texi, user/stackchk.t, user/task.t, user/userext.t: Add new Object Services collection. Tidy up some configuration documentation from earlier changes.
  • user/object.t: New file.
  • Property mode set to 100644
File size: 7.2 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2007.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Stack Bounds Checker
10
11@section Introduction
12
13The stack bounds checker is an RTEMS support component that determines
14if a task has overrun its run-time stack.  The routines provided
15by the stack bounds checker manager are:
16
17@itemize @bullet
18@item @code{@value{DIRPREFIX}stack_checker_is_blown} - Has the Current Task Blown its Stack
19@item @code{@value{DIRPREFIX}stack_checker_report_usage} - Report Task Stack Usage
20@end itemize
21
22@section Background
23
24@subsection Task Stack
25
26Each task in a system has a fixed size stack associated with it.  This
27stack is allocated when the task is created.  As the task executes, the
28stack is used to contain parameters, return addresses, saved registers,
29and local variables.  The amount of stack space required by a task
30is dependent on the exact set of routines used.  The peak stack usage
31reflects the worst case of subroutine pushing information on the stack.
32For example, if a subroutine allocates a local buffer of 1024 bytes, then
33this data must be accounted for in the stack of every task that invokes that
34routine.
35
36Recursive routines make calculating peak stack usage difficult, if not
37impossible.  Each call to the recursive routine consumes @i{n} bytes
38of stack space.  If the routine recursives 1000 times, then
39@code{1000 * @i{n}} bytes of stack space are required.
40
41@subsection Execution
42
43The stack bounds checker operates as a set of task extensions.  At
44task creation time, the task's stack is filled with a pattern to
45indicate the stack is unused.  As the task executes, it will overwrite
46this pattern in memory.  At each task switch, the stack bounds checker's
47task switch extension is executed.  This extension checks that:
48
49@itemize @bullet
50
51@item the last @code{n} bytes of the task's stack have
52not been overwritten.  If this pattern has been damaged, it
53indicates that at some point since this task was context
54switch to the CPU, it has used too much stack space.
55
56@item the current stack pointer of the task is not within
57the address range allocated for use as the task's stack.
58
59@end itemize
60
61If either of these conditions is detected, then a blown stack
62error is reported using the @code{printk} routine.
63
64The number of bytes checked for an overwrite is processor family dependent.
65The minimum stack frame per subroutine call varies widely between processor
66families.  On CISC families like the Motorola MC68xxx and Intel ix86, all
67that is needed is a return address.  On more complex RISC processors,
68the minimum stack frame per subroutine call may include space to save
69a significant number of registers.
70
71Another processor dependent feature that must be taken into account by
72the stack bounds checker is the direction that the stack grows.  On some
73processor families, the stack grows up or to higher addresses as the
74task executes.  On other families, it grows down to lower addresses.  The
75stack bounds checker implementation uses the stack description definitions
76provided by every RTEMS port to get for this information.
77
78@section Operations
79
80@subsection Initializing the Stack Bounds Checker
81
82The stack checker is initialized automatically when its task
83create extension runs for the first time.
84
85The application must include the stack bounds checker extension set
86in its set of Initial Extensions.  This set of extensions is
87defined as @code{STACK_CHECKER_EXTENSION}.  If using @code{<rtems/confdefs.h>}
88for Configuration Table generation, then all that is necessary is
89to define the macro @code{STACK_CHECKER_ON} before including
90@code{<rtems/confdefs.h>} as shown below:
91
92@example
93@group
94#define STACK_CHECKER_ON
95  ...
96#include <rtems/confdefs.h>
97@end group
98@end example
99
100@subsection Checking for Blown Task Stack
101
102The application may check whether the stack pointer of currently
103executing task is within proper bounds at any time by calling
104the @code{@value{DIRPREFIX}stack_checker_is_blown} method.  This
105method return @code{FALSE} if the task is operating within its
106stack bounds and has not damaged its pattern area.
107
108@subsection Reporting Task Stack Usage
109
110The application may dynamically report the stack usage for every task
111in the system by calling the
112@code{@value{DIRPREFIX}stack_checker_report_usage} routine.
113This routine prints a table with the peak usage and stack size of
114every task in the system.  The following is an example of the
115report generated:
116
117@example
118@group
119    ID      NAME       LOW        HIGH     AVAILABLE      USED
1200x04010001  IDLE  0x003e8a60  0x003e9667       2952        200
1210x08010002  TA1   0x003e5750  0x003e7b57       9096       1168
1220x08010003  TA2   0x003e31c8  0x003e55cf       9096       1168
1230x08010004  TA3   0x003e0c40  0x003e3047       9096       1104
1240xffffffff  INTR  0x003ecfc0  0x003effbf      12160        128
125@end group
126@end example
127
128Notice the last time.  The task id is 0xffffffff and its name is "INTR".
129This is not actually a task, it is the interrupt stack.
130
131@subsection When a Task Overflows the Stack
132
133When the stack bounds checker determines that a stack overflow has occurred,
134it will attempt to print a message using @code{printk} identifying the
135task and then shut the system down.  If the stack overflow has caused
136corruption, then it is possible that the message can not be printed.
137
138The following is an example of the output generated:
139
140@example
141@group
142BLOWN STACK!!! Offending task(0x3eb360): id=0x08010002; name=0x54413120
143  stack covers range 0x003e5750 - 0x003e7b57 (9224 bytes)
144  Damaged pattern begins at 0x003e5758 and is 128 bytes long
145@end group
146@end example
147
148The above includes the task id and a pointer to the task control block as
149well as enough information so one can look at the task's stack and
150see what was happening.
151
152@section Routines
153
154This section details the stack bounds checker's routines.
155A subsection is dedicated to each of routines
156and describes the calling sequence, related constants, usage,
157and status codes.
158
159
160@c
161@c  rtems_stack_checker_is_blown
162@c
163@page
164@subsection STACK_CHECKER_IS_BLOWN - Has Current Task Blown Its Stack
165
166@subheading CALLING SEQUENCE:
167
168@ifset is-C
169@example
170boolean rtems_stack_checker_is_blown( void );
171@end example
172@end ifset
173
174@ifset is-Ada
175@example
176function Stack_Checker_Is_Blown return RTEMS.Boolean;
177@end example
178@end ifset
179
180@subheading STATUS CODES:
181@code{TRUE} - Stack is operating within its stack limits@*
182@code{FALSE} - Current stack pointer is outside allocated area
183
184
185@subheading DESCRIPTION:
186
187This method is used to determine if the current stack pointer
188of the currently executing task is within bounds.
189
190@subheading NOTES:
191
192This method checks the current stack pointer against
193the high and low addresses of the stack memory allocated when
194the task was created and it looks for damage to the high water
195mark pattern for the worst case usage of the task being called.
196
197@page
198@subsection STACK_CHECKER_REPORT_USAGE - Report Task Stack Usage
199
200@subheading CALLING SEQUENCE:
201
202@ifset is-C
203@example
204void rtems_stack_checker_report_usage( void );
205@end example
206@end ifset
207
208@ifset is-Ada
209@example
210procedure Stack_Checker_Report_Usage;
211@end example
212@end ifset
213
214@subheading STATUS CODES: NONE
215
216@subheading DESCRIPTION:
217
218This routine prints a table with the peak stack usage and stack space
219allocation of every task in the system.
220
221@subheading NOTES:
222
223NONE
Note: See TracBrowser for help on using the repository browser.