diff options
author | Joel Sherrill <joel.sherrill@OARcorp.com> | 2007-05-11 20:00:30 +0000 |
---|---|---|
committer | Joel Sherrill <joel.sherrill@OARcorp.com> | 2007-05-11 20:00:30 +0000 |
commit | e974f9d78636db62dc816a8728e88cade3705bd6 (patch) | |
tree | ffb5792511ed822f6039e2050840685114abdbce /doc/user | |
parent | 2007-05-11 Joel Sherrill <joel.sherrill@OARcorp.com> (diff) | |
download | rtems-e974f9d78636db62dc816a8728e88cade3705bd6.tar.bz2 |
2007-05-11 Joel Sherrill <joel.sherrill@OARcorp.com>
* user/.cvsignore, user/cpuuse.t, user/stackchk.t: Stack checker and
CPU usage chapters are now OK in the manual.
Diffstat (limited to 'doc/user')
-rw-r--r-- | doc/user/.cvsignore | 1 | ||||
-rw-r--r-- | doc/user/cpuuse.t | 29 | ||||
-rw-r--r-- | doc/user/stackchk.t | 77 |
3 files changed, 78 insertions, 29 deletions
diff --git a/doc/user/.cvsignore b/doc/user/.cvsignore index bbf7de1754..79dc66fa4b 100644 --- a/doc/user/.cvsignore +++ b/doc/user/.cvsignore @@ -1,3 +1,4 @@ +barrier.texi bsp.texi clock.texi concepts.texi diff --git a/doc/user/cpuuse.t b/doc/user/cpuuse.t index 161df741cd..4c67c58432 100644 --- a/doc/user/cpuuse.t +++ b/doc/user/cpuuse.t @@ -1,5 +1,5 @@ @c -@c COPYRIGHT (c) 1988-2002. +@c COPYRIGHT (c) 1988-2007. @c On-Line Applications Research Corporation (OAR). @c All rights reserved. @c @@ -22,11 +22,28 @@ The routines provided by the CPU usage statistics manager are: @section Background -@section Operations +When analyzing and debugging real-time applications, it is important +to be able to know how much CPU time each task in the system consumes. +This support component provides a mechanism to easily obtain this +information with little burden placed on the target. + +The raw data is gathered as part of performing a context switch. RTEMS +keeps track of how many clock ticks have occurred which the task being +switched out has been executing. If the task has been running less than +1 clock tick, then for the purposes of the statistics, it is assumed to +have executed 1 clock tick. This results in some inaccuracy but the +alternative is for the task to have appeared to execute 0 clock ticks. + +RTEMS versions newer than the 4.7 release series, support the ability +to obtain timestamps with nanosecond granularity if the BSP provides +support. It is a desirable enhancement to change the way the usage +data is gathered to take advantage of this recently added capability. +Please consider sponsoring the core RTEMS development team to add +this capability. -@section Report CPU Usage Statistics +@section Operations -@subsection Reporting Period Statistics +@subsection Report CPU Usage Statistics The application may dynamically report the CPU usage for every task in the system by calling the @@ -72,7 +89,7 @@ some type of debug interface. It is usually fine to think of the total idle time as being the sum of the IDLE task and a debug task that will not be included in a production build of an application. -@section Reset CPU Usage Statistics +@subsection Reset CPU Usage Statistics Invoking the @code{@value{DIRPREFIX}cpu_usage_reset} routine resets the CPU usage statistics for all tasks in the system. @@ -110,7 +127,7 @@ all tasks in the system. @subheading NOTES: -NONE +The table is printed using the @code{printk} routine. @page @subsection cpu_usage_reset - Reset CPU Usage Statistics diff --git a/doc/user/stackchk.t b/doc/user/stackchk.t index 0d975265e6..64e529de9e 100644 --- a/doc/user/stackchk.t +++ b/doc/user/stackchk.t @@ -1,5 +1,5 @@ @c -@c COPYRIGHT (c) 1988-2006. +@c COPYRIGHT (c) 1988-2007. @c On-Line Applications Research Corporation (OAR). @c All rights reserved. @c @@ -11,11 +11,11 @@ @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 +if a task has overrun 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_is_blown} - Has the Current Task Blown its Stack @item @code{@value{DIRPREFIX}stack_checker_report_usage} - Report Task Stack Usage @end itemize @@ -35,8 +35,8 @@ 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. +of stack space. If the routine recursives 1000 times, then +@code{1000 * @i{n}} bytes of stack space are required. @subsection Execution @@ -44,9 +44,22 @@ 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. +task switch extension is executed. This extension checks that: + +@itemize @bullet + +@item the last @code{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. + +@item the current stack pointer of the task is not within +the address range allocated for use as the task's stack. + +@end itemize + +If either of these conditions is detected, then a blown stack +error is reported using the @code{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 @@ -67,28 +80,36 @@ provided by every RTEMS port to get for this information. @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. +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 @code{STACK_CHECKER_EXTENSION}. If using @code{<confdefs.h>} +defined as @code{STACK_CHECKER_EXTENSION}. If using @code{<rtems/confdefs.h>} for Configuration Table generation, then all that is necessary is to define the macro @code{STACK_CHECKER_ON} before including -@code{<confdefs.h>} as shown below: +@code{<rtems/confdefs.h>} as shown below: @example @group #define STACK_CHECKER_ON ... -#include <confdefs.h> +#include <rtems/confdefs.h> @end group @end example +@subsection 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 @code{@value{DIRPREFIX}stack_checker_is_blown} method. This +method return @code{FALSE} if the task is operating within its +stack bounds and has not damaged its pattern area. + @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_report_usage} routine. +in the system by calling the +@code{@value{DIRPREFIX}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: @@ -110,9 +131,9 @@ 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. +it will attempt to print a message using @code{printk} 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: @@ -135,14 +156,18 @@ A subsection is dedicated to each of routines and describes the calling sequence, related constants, usage, and status codes. + +@c +@c rtems_stack_checker_is_blown +@c @page -@subsection stack_checker_initialize - Initialize the Stack Bounds Checker +@subsection stack_checker_is_blown - Has Current Task Blown Its Stack @subheading CALLING SEQUENCE: @ifset is-C @example -void rtems_stack_checker_initialize( void ); +boolean rtems_stack_checker_is_blown( void ); @end example @end ifset @@ -152,16 +177,22 @@ An Ada interface is not currently available. @end example @end ifset -@subheading STATUS CODES: NONE +@subheading STATUS CODES: +@code{TRUE} - Stack is operating within its stack limits@* +@code{FALSE} - Current stack pointer is outside allocated area + @subheading DESCRIPTION: -Initialize the stack bounds checker. +This method is used to determine if the current stack pointer +of the currently executing task is within bounds. @subheading NOTES: -This is performed automatically the first time the stack bounds checker -task create extension executes. +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. @page @subsection stack_checker_report_usage - Report Task Stack Usage |