From 72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 3 Nov 2016 16:58:08 +1100 Subject: Rename all manuals with an _ to have a -. It helps released naming of files. --- c-user/stack_bounds_checker.rst | 210 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 c-user/stack_bounds_checker.rst (limited to 'c-user/stack_bounds_checker.rst') diff --git a/c-user/stack_bounds_checker.rst b/c-user/stack_bounds_checker.rst new file mode 100644 index 0000000..0ce5a44 --- /dev/null +++ b/c-user/stack_bounds_checker.rst @@ -0,0 +1,210 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + +Stack Bounds Checker +#################### + +.. index:: stack + +Introduction +============ + +The stack bounds checker is an RTEMS support component that determines if a +task has overrun its run-time stack. The routines provided by the stack bounds +checker manager are: + +- rtems_stack_checker_is_blown_ - Has the Current Task Blown its Stack + +- rtems_stack_checker_report_usage_ - Report Task Stack Usage + +Background +========== + +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 *n* bytes of stack +space. If the routine recursives 1000 times, then ``1000 * n`` bytes of +stack space are required. + +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 ``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. + +- the current stack pointer of the task is not within the address range + allocated for use as the task's stack. + +If either of these conditions is detected, then a blown stack error is reported +using the ``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 +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. + +Operations +========== + +Initializing the Stack Bounds Checker +------------------------------------- + +The stack checker is initialized automatically when its task 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 +``STACK_CHECKER_EXTENSION``. If using ```` for Configuration +Table generation, then all that is necessary is to define the macro +``CONFIGURE_STACK_CHECKER_ENABLED`` before including ```` as +shown below: + +.. code-block:: c + + #define CONFIGURE_STACK_CHECKER_ENABLED + ... + #include + +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 +``rtems_stack_checker_is_blown`` method. This method return ``FALSE`` if the +task is operating within its stack bounds and has not damaged its pattern area. + +Reporting Task Stack Usage +-------------------------- + +The application may dynamically report the stack usage for every task in the +system by calling the ``rtems_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: + +.. code-block:: c + + 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 + +Notice the last line. The task id is ``0xffffffff`` and its name is ``INTR``. +This is not actually a task, it is the interrupt stack. + +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 using ``printk`` identifying the task and then +shut the system down. If the stack overflow has caused corruption, then it is +possible that the message cannot be printed. + +The following is an example of the output generated: + +.. code-block:: c + + 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 + +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. + +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. + +.. COMMENT: rtems_stack_checker_is_blown + +.. _rtems_stack_checker_is_blown: + +STACK_CHECKER_IS_BLOWN - Has Current Task Blown Its Stack +--------------------------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + bool rtems_stack_checker_is_blown( void ); + +**STATUS CODES:** + +.. list-table:: + :class: rtems-table + + * - ``TRUE`` + - Stack is operating within its stack limits + * - ``FALSE`` + - Current stack pointer is outside allocated area + +**DESCRIPTION:** + +This method is used to determine if the current stack pointer of the currently +executing task is within bounds. + +**NOTES:** + +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. + +.. _rtems_stack_checker_report_usage: + +STACK_CHECKER_REPORT_USAGE - Report Task Stack Usage +---------------------------------------------------- + +**CALLING SEQUENCE:** + +.. code-block:: c + + void rtems_stack_checker_report_usage( void ); + +**STATUS CODES:** + +NONE + +**DESCRIPTION:** + +This routine prints a table with the peak stack usage and stack space +allocation of every task in the system. + +**NOTES:** + +NONE -- cgit v1.2.3