source: rtems-docs/c-user/stack_bounds_checker.rst @ c2ee227

5
Last change on this file since c2ee227 was 6c56401, checked in by Chris Johns <chrisj@…>, on 11/12/17 at 03:34:48

c-user: Fix index locations.

Update #3229.

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