From 0d86b7111e378286bd61613c363c06cec39d0538 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 18 Feb 2016 15:29:28 +1100 Subject: Clean up. --- c_user/stack_bounds_checker.rst | 180 +++++++++++++++++++++------------------- 1 file changed, 95 insertions(+), 85 deletions(-) (limited to 'c_user/stack_bounds_checker.rst') diff --git a/c_user/stack_bounds_checker.rst b/c_user/stack_bounds_checker.rst index 0cf075b..b7a0ff1 100644 --- a/c_user/stack_bounds_checker.rst +++ b/c_user/stack_bounds_checker.rst @@ -1,16 +1,22 @@ +.. 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: +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_is_blown_ - Has the Current Task Blown its Stack -- ``rtems_stack_checker_report_usage`` - Report Task Stack Usage +- rtems_stack_checker_report_usage_ - Report Task Stack Usage Background ========== @@ -18,53 +24,52 @@ 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. +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. +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 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 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. +- 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. +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. +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 ========== @@ -72,14 +77,16 @@ Operations Initializing the Stack Bounds Checker ------------------------------------- -The stack checker is initialized automatically when its task -create extension runs for the first time. +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: -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:: c #define CONFIGURE_STACK_CHECKER_ENABLED @@ -89,20 +96,19 @@ to define the macro ``CONFIGURE_STACK_CHECKER_ENABLED`` before including``