From aba8a85d4bd98a84d8e2b1e94bfb77fdd0b8a57e Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Wed, 13 Sep 2006 16:21:09 +0000 Subject: 2006-09-13 Joel Sherrill * new_chapters/Makefile.am, user/Makefile.am, user/c_user.texi, user/dirstat.texi, user/task.t: Move stack to first class citizen status. Include it in User Manual and rename to start with rtems_. * user/stackchk.t: New file. * new_chapters/stackchk.t: Removed. --- doc/ChangeLog | 16 ++++ doc/new_chapters/Makefile.am | 11 +-- doc/new_chapters/stackchk.t | 192 ------------------------------------------- doc/user/Makefile.am | 12 ++- doc/user/c_user.texi | 4 +- doc/user/dirstat.texi | 4 +- doc/user/stackchk.t | 192 +++++++++++++++++++++++++++++++++++++++++++ doc/user/task.t | 2 +- 8 files changed, 225 insertions(+), 208 deletions(-) delete mode 100644 doc/new_chapters/stackchk.t create mode 100644 doc/user/stackchk.t diff --git a/doc/ChangeLog b/doc/ChangeLog index 53b467c93c..fabcd9a311 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,19 @@ +2006-09-13 Joel Sherrill + + * new_chapters/Makefile.am, user/Makefile.am, user/c_user.texi, + user/dirstat.texi, user/task.t: Move stack to first class citizen + status. Include it in User Manual and rename to start with rtems_. + * user/stackchk.t: New file. + * new_chapters/stackchk.t: Removed. + +2006-09-13 Joel Sherrill + + * new_chapters/Makefile.am, user/Makefile.am, user/c_user.texi, + user/dirstat.texi, user/task.t: Move stack to first class citizen + status. Include it in User Manual and rename to start with rtems_. + * user/stackchk.t: New file. + * new_chapters/stackchk.t: Removed. + 2006-09-07 Ken Peters PR 1171/doc diff --git a/doc/new_chapters/Makefile.am b/doc/new_chapters/Makefile.am index 03bc2a8083..017bbd6d93 100644 --- a/doc/new_chapters/Makefile.am +++ b/doc/new_chapters/Makefile.am @@ -13,8 +13,7 @@ include $(top_srcdir)/project.am include $(top_srcdir)/main.am GENERATED_FILES = \ - stackchk.texi rtmonuse.texi cpuuse.texi error.texi \ - monitor.texi + rtmonuse.texi cpuuse.texi error.texi monitor.texi COMMON_FILES += $(top_srcdir)/common/cpright.texi @@ -23,11 +22,6 @@ FILES = info_TEXINFOS = new_chapters.texi new_chapters_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES) -stackchk.texi: stackchk.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - rtmonuse.texi: rtmonuse.t $(BMENU2) -p "" \ -u "Top" \ @@ -50,8 +44,7 @@ monitor.texi: monitor.t noinst_SCRIPTS = gen_section -EXTRA_DIST = cpuuse.t error.t \ - monitor.t rtmonuse.t stackchk.t STATUS TODO \ +EXTRA_DIST = cpuuse.t error.t monitor.t rtmonuse.t STATUS TODO \ $(noinst_SCRIPTS) CLEANFILES += new_chapters.info new_chapters.info-? diff --git a/doc/new_chapters/stackchk.t b/doc/new_chapters/stackchk.t deleted file mode 100644 index 1994ea5d49..0000000000 --- a/doc/new_chapters/stackchk.t +++ /dev/null @@ -1,192 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@c - -@chapter Stack Bounds Checker - -@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 -by the stack bounds checker manager are: - -@itemize @bullet -@item @code{Stack_check_Initialize} - Initialize the Stack Bounds Checker -@item @code{Stack_check_Dump_usage} - Report Task Stack Usage -@end itemize - -@section Background - -@subsection 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 @i{n} bytes -of stack space. If the routine recursives 1000 times, then @code{1000 * @i{n}} -bytes of stack space are required. - -@subsection 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 -@code{n} bytes of the task's stack have not been overwritten. If they -have, then a blown stack error is reported. - -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. - -@section Operations - -@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{Stack_check_Initialize} is invoked. - -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{} -for Configuration Table generation, then all that is necessary is -to define the macro @code{STACK_CHECKER_ON} before including -@code{} as shown below: - -@example -@group -#define STACK_CHECKER_ON - ... -#include -@end group -@end example - -@subsection Reporting Task Stack Usage - -The application may dynamically report the stack usage for every task -in the system by calling the @code{Stack_check_Dump_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: - -@example -@group - 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 -@end group -@end example - -Notice the last time. The task id is 0xffffffff and its name is "INTR". -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. - -The following is an example of the output generated: - -@example -@group -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 -@end group -@end example - -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. - -@section 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. - -@page -@subsection Stack_check_Initialize - Initialize the Stack Bounds Checker - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -void Stack_check_Initialize( void ); -@end example -@end ifset - -@ifset is-Ada -@example -An Ada interface is not currently available. -@end example -@end ifset - -@subheading STATUS CODES: NONE - -@subheading DESCRIPTION: - -Initialize the stack bounds checker. - -@subheading NOTES: - -This is performed automatically the first time the stack bounds checker -task create extension executes. - -@page -@subsection Stack_check_Dump_usage - Report Task Stack Usage - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -void Stack_check_Dump_usage( void ); -@end example -@end ifset - -@ifset is-Ada -@example -An Ada interface is not currently available. -@end example -@end ifset - -@subheading STATUS CODES: NONE - -@subheading DESCRIPTION: - -This routine prints a table with the peak stack usage and stack space -allocation of every task in the system. - -@subheading NOTES: - -NONE diff --git a/doc/user/Makefile.am b/doc/user/Makefile.am index 90182f51b4..8aaf34c041 100644 --- a/doc/user/Makefile.am +++ b/doc/user/Makefile.am @@ -17,7 +17,8 @@ FILES = bsp.texi dirstat.texi example.texi glossary.texi preface.texi GENERATED_FILES = overview.texi concepts.texi datatypes.texi init.texi \ task.texi intr.texi clock.texi timer.texi sem.texi msg.texi event.texi \ signal.texi part.texi region.texi dpmem.texi io.texi fatal.texi \ - schedule.texi rtmon.texi bsp.texi userext.texi conf.texi mp.texi + schedule.texi rtmon.texi bsp.texi userext.texi conf.texi mp.texi \ + stackchk.texi COMMON_FILES += $(top_srcdir)/common/cpright.texi @@ -155,12 +156,17 @@ conf.texi: conf.t mp.texi: mp.t $(BMENU2) -p "Configuring a System Sizing the RTEMS RAM Workspace" \ + -u "Top" \ + -n "Stack Bounds Checker" < $< > $@ + +stackchk.texi: stackchk.t + $(BMENU2) -p "Multiprocessing Manager MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet" \ -u "Top" \ -n "Directive Status Codes" < $< > $@ EXTRA_DIST = bsp.t concepts.t clock.t datatypes.t conf.t dpmem.t event.t \ fatal.t init.t intr.t io.t mp.t msg.t overview.t part.t region.t rtmon.t \ - sem.t schedule.t signal.t task.t timer.t userext.t $(TXT_FILES) $(PNG_FILES) \ - $(EPS_IMAGES) $(noinst_DATA) + sem.t schedule.t signal.t stackchk.t task.t timer.t userext.t \ + $(TXT_FILES) $(PNG_FILES) $(EPS_IMAGES) $(noinst_DATA) CLEANFILES += c_user.info c_user.info-? c_user.info-?? diff --git a/doc/user/c_user.texi b/doc/user/c_user.texi index 4ade92d03d..3336c1dae5 100644 --- a/doc/user/c_user.texi +++ b/doc/user/c_user.texi @@ -7,7 +7,7 @@ @c %**end of header @c -@c COPYRIGHT (c) 1988-2002. +@c COPYRIGHT (c) 1988-2006. @c On-Line Applications Research Corporation (OAR). @c All rights reserved. @c @@ -100,6 +100,7 @@ @include userext.texi @include conf.texi @include mp.texi +@include stackchk.texi @include dirstat.texi @include example.texi @include glossary.texi @@ -134,6 +135,7 @@ This is the online version of the RTEMS C User's Guide. * User Extensions Manager:: * Configuring a System:: * Multiprocessing Manager:: +* Stack Bounds Checker:: * Directive Status Codes:: * Example Application:: * Glossary:: diff --git a/doc/user/dirstat.texi b/doc/user/dirstat.texi index 094bcf2b13..e7576e40e6 100644 --- a/doc/user/dirstat.texi +++ b/doc/user/dirstat.texi @@ -1,5 +1,5 @@ @c -@c COPYRIGHT (c) 1988-2002. +@c COPYRIGHT (c) 1988-2006. @c On-Line Applications Research Corporation (OAR). @c All rights reserved. @c @@ -7,7 +7,7 @@ @c @ifinfo -@node Directive Status Codes, Example Application, Multiprocessing Manager MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet, Top +@node Directive Status Codes, Example Application, Stack Bounds Checker stack_checker_dump_usage - Report Task Stack Usage, Top @end ifinfo @chapter Directive Status Codes @table @b diff --git a/doc/user/stackchk.t b/doc/user/stackchk.t new file mode 100644 index 0000000000..00cde1b386 --- /dev/null +++ b/doc/user/stackchk.t @@ -0,0 +1,192 @@ +@c +@c COPYRIGHT (c) 1988-2006. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Stack Bounds Checker + +@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 +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_dump_usage} - Report Task Stack Usage +@end itemize + +@section Background + +@subsection 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 @i{n} bytes +of stack space. If the routine recursives 1000 times, then @code{1000 * @i{n}} +bytes of stack space are required. + +@subsection 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 +@code{n} bytes of the task's stack have not been overwritten. If they +have, then a blown stack error is reported. + +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. + +@section Operations + +@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. + +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{} +for Configuration Table generation, then all that is necessary is +to define the macro @code{STACK_CHECKER_ON} before including +@code{} as shown below: + +@example +@group +#define STACK_CHECKER_ON + ... +#include +@end group +@end example + +@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_dump_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: + +@example +@group + 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 +@end group +@end example + +Notice the last time. The task id is 0xffffffff and its name is "INTR". +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. + +The following is an example of the output generated: + +@example +@group +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 +@end group +@end example + +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. + +@section 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. + +@page +@subsection stack_checker_initialize - Initialize the Stack Bounds Checker + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +void rtems_stack_checker_initialize( void ); +@end example +@end ifset + +@ifset is-Ada +@example +An Ada interface is not currently available. +@end example +@end ifset + +@subheading STATUS CODES: NONE + +@subheading DESCRIPTION: + +Initialize the stack bounds checker. + +@subheading NOTES: + +This is performed automatically the first time the stack bounds checker +task create extension executes. + +@page +@subsection stack_checker_dump_usage - Report Task Stack Usage + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +void rtems_stack_checker_dump_usage( void ); +@end example +@end ifset + +@ifset is-Ada +@example +An Ada interface is not currently available. +@end example +@end ifset + +@subheading STATUS CODES: NONE + +@subheading DESCRIPTION: + +This routine prints a table with the peak stack usage and stack space +allocation of every task in the system. + +@subheading NOTES: + +NONE diff --git a/doc/user/task.t b/doc/user/task.t index 115536eb22..8ad87d0760 100644 --- a/doc/user/task.t +++ b/doc/user/task.t @@ -1,5 +1,5 @@ @c -@c COPYRIGHT (c) 1988-2002. +@c COPYRIGHT (c) 1988-2006. @c On-Line Applications Research Corporation (OAR). @c All rights reserved. @c -- cgit v1.2.3