RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

2007-05-11 Joel Sherrill <joel.sherrill@OARcorp.com>

Browse Source 
* user/.cvsignore, user/cpuuse.t, user/stackchk.t: Stack checker and
	CPU usage chapters are now OK in the manual.
This commit is contained in:
Joel Sherrill
2007-05-11 20:00:30 +00:00
parent 71531a6fa0
commit e974f9d786
4 changed files with 83 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
doc/ChangeLog
View File

@@ -1,3 +1,8 @@
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.
2007-05-09 Ralf Corsépius <ralf.corsepius@rtems.org> 2007-05-09 Ralf Corsépius <ralf.corsepius@rtems.org>
* porting/miscellaneous.t: Remove subsection on "Optional * porting/miscellaneous.t: Remove subsection on "Optional

1
doc/user/.cvsignore
View File

@@ -1,3 +1,4 @@
barrier.texi
bsp.texi bsp.texi
clock.texi clock.texi
concepts.texi concepts.texi

29
doc/user/cpuuse.t
View File

@@ -1,5 +1,5 @@
@c @c
@c COPYRIGHT (c) 1988-2002. @c COPYRIGHT (c) 1988-2007.
@c On-Line Applications Research Corporation (OAR). @c On-Line Applications Research Corporation (OAR).
@c All rights reserved. @c All rights reserved.
@c @c
@@ -22,11 +22,28 @@ The routines provided by the CPU usage statistics manager are:
@section Background @section Background
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 Operations @section Operations
@section Report CPU Usage Statistics @subsection Report CPU Usage Statistics
@subsection Reporting Period Statistics
The application may dynamically report the CPU usage for every The application may dynamically report the CPU usage for every
task in the system by calling the 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 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. 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 Invoking the @code{@value{DIRPREFIX}cpu_usage_reset} routine resets
the CPU usage statistics for all tasks in the system. the CPU usage statistics for all tasks in the system.
@@ -110,7 +127,7 @@ all tasks in the system.
@subheading NOTES: @subheading NOTES:
NONE The table is printed using the @code{printk} routine.
@page @page
@subsection cpu_usage_reset - Reset CPU Usage Statistics @subsection cpu_usage_reset - Reset CPU Usage Statistics

77
doc/user/stackchk.t
View File

@@ -1,5 +1,5 @@
@c @c
@c COPYRIGHT (c) 1988-2006. @c COPYRIGHT (c) 1988-2007.
@c On-Line Applications Research Corporation (OAR). @c On-Line Applications Research Corporation (OAR).
@c All rights reserved. @c All rights reserved.
@c @c
@@ -11,11 +11,11 @@
@section Introduction @section Introduction
The stack bounds checker is an RTEMS support component that determines 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: by the stack bounds checker manager are:
@itemize @bullet @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 @item @code{@value{DIRPREFIX}stack_checker_report_usage} - Report Task Stack Usage
@end itemize @end itemize
@@ -35,8 +35,8 @@ routine.
Recursive routines make calculating peak stack usage difficult, if not Recursive routines make calculating peak stack usage difficult, if not
impossible. Each call to the recursive routine consumes @i{n} bytes 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}} of stack space. If the routine recursives 1000 times, then
bytes of stack space are required. @code{1000 * @i{n}} bytes of stack space are required.
@subsection Execution @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 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 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 this pattern in memory. At each task switch, the stack bounds checker's
task switch extension is executed. This extension checks that the last task switch extension is executed. This extension checks that:
@code{n} bytes of the task's stack have not been overwritten. If they
have, then a blown stack error is reported. @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 number of bytes checked for an overwrite is processor family dependent.
The minimum stack frame per subroutine call varies widely between processor 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 @subsection Initializing the Stack Bounds Checker
The stack checker is initialized automatically when its task The stack checker is initialized automatically when its task
create extension runs for the first time. When this occurs, create extension runs for the first time.
the @code{@value{DIRPREFIX}stack_checker_initialize} is invoked.
The application must include the stack bounds checker extension set The application must include the stack bounds checker extension set
in its set of Initial Extensions. This set of extensions is 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 for Configuration Table generation, then all that is necessary is
to define the macro @code{STACK_CHECKER_ON} before including to define the macro @code{STACK_CHECKER_ON} before including
@code{<confdefs.h>} as shown below: @code{<rtems/confdefs.h>} as shown below:
@example @example
@group @group
#define STACK_CHECKER_ON #define STACK_CHECKER_ON
... ...
#include <confdefs.h> #include <rtems/confdefs.h>
@end group @end group
@end example @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 @subsection Reporting Task Stack Usage
The application may dynamically report the stack usage for every task 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 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 every task in the system. The following is an example of the
report generated: report generated:
@@ -110,9 +131,9 @@ This is not actually a task, it is the interrupt stack.
@subsection When a Task Overflows the Stack @subsection When a Task Overflows the Stack
When the stack bounds checker determines that a stack overflow has occurred, 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 it will attempt to print a message using @code{printk} identifying the
system down. If the stack overflow has caused corruption, then it is task and then shut the system down. If the stack overflow has caused
possible that the message can not be printed. corruption, then it is possible that the message can not be printed.
The following is an example of the output generated: 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 describes the calling sequence, related constants, usage,
and status codes. and status codes.
@c
@c rtems_stack_checker_is_blown
@c
@page @page
@subsection stack_checker_initialize - Initialize the Stack Bounds Checker @subsection stack_checker_is_blown - Has Current Task Blown Its Stack
@subheading CALLING SEQUENCE: @subheading CALLING SEQUENCE:
@ifset is-C @ifset is-C
@example @example
void rtems_stack_checker_initialize( void ); boolean rtems_stack_checker_is_blown( void );
@end example @end example
@end ifset @end ifset
@@ -152,16 +177,22 @@ An Ada interface is not currently available.
@end example @end example
@end ifset @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: @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: @subheading NOTES:
This is performed automatically the first time the stack bounds checker This method checks the current stack pointer against
task create extension executes. 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 @page
@subsection stack_checker_report_usage - Report Task Stack Usage @subsection stack_checker_report_usage - Report Task Stack Usage