Changeset e974f9d7 in rtems


Ignore:
Timestamp:
May 11, 2007, 8:00:30 PM (13 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
4da36c1a
Parents:
71531a6
Message:

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

  • user/.cvsignore, user/cpuuse.t, user/stackchk.t: Stack checker and CPU usage chapters are now OK in the manual.
Location:
doc
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • doc/ChangeLog

    r71531a6 re974f9d7  
     12007-05-11      Joel Sherrill <joel.sherrill@OARcorp.com>
     2
     3        * user/.cvsignore, user/cpuuse.t, user/stackchk.t: Stack checker and
     4        CPU usage chapters are now OK in the manual.
     5
    162007-05-09      Ralf Corsépius <ralf.corsepius@rtems.org>
    27
  • doc/user/.cvsignore

    r71531a6 re974f9d7  
     1barrier.texi
    12bsp.texi
    23clock.texi
  • doc/user/cpuuse.t

    r71531a6 re974f9d7  
    11@c
    2 @c  COPYRIGHT (c) 1988-2002.
     2@c  COPYRIGHT (c) 1988-2007.
    33@c  On-Line Applications Research Corporation (OAR).
    44@c  All rights reserved.
     
    2323@section Background
    2424
     25When analyzing and debugging real-time applications, it is important
     26to be able to know how much CPU time each task in the system consumes.
     27This support component provides a mechanism to easily obtain this
     28information with little burden placed on the target.
     29
     30The raw data is gathered as part of performing a context switch.  RTEMS
     31keeps track of how many clock ticks have occurred which the task being
     32switched out has been executing.  If the task has been running less than
     331 clock tick, then for the purposes of the statistics, it is assumed to
     34have executed 1 clock tick.  This results in some inaccuracy but the
     35alternative is for the task to have appeared to execute 0 clock ticks.
     36
     37RTEMS versions newer than the 4.7 release series, support the ability
     38to obtain timestamps with nanosecond granularity if the BSP provides
     39support.  It is a desirable enhancement to change the way the usage
     40data is gathered to take advantage of this recently added capability.
     41Please consider sponsoring the core RTEMS development team to add
     42this capability.
     43
    2544@section Operations
    2645
    27 @section Report CPU Usage Statistics
    28 
    29 @subsection Reporting Period Statistics
     46@subsection Report CPU Usage Statistics
    3047
    3148The application may dynamically report the CPU usage for every
     
    7390task that will not be included in a production build of an application.
    7491
    75 @section Reset CPU Usage Statistics
     92@subsection Reset CPU Usage Statistics
    7693
    7794Invoking the @code{@value{DIRPREFIX}cpu_usage_reset} routine resets
     
    111128@subheading NOTES:
    112129
    113 NONE
     130The table is printed using the @code{printk} routine.
    114131
    115132@page
  • doc/user/stackchk.t

    r71531a6 re974f9d7  
    11@c
    2 @c  COPYRIGHT (c) 1988-2006.
     2@c  COPYRIGHT (c) 1988-2007.
    33@c  On-Line Applications Research Corporation (OAR).
    44@c  All rights reserved.
     
    1212
    1313The stack bounds checker is an RTEMS support component that determines
    14 if a task has overflowed its run-time stack.  The routines provided
     14if a task has overrun its run-time stack.  The routines provided
    1515by the stack bounds checker manager are:
    1616
    1717@itemize @bullet
    18 @item @code{@value{DIRPREFIX}stack_checker_initialize} - Initialize the Stack Bounds Checker
     18@item @code{@value{DIRPREFIX}stack_checker_is_blown} - Has the Current Task Blown its Stack
    1919@item @code{@value{DIRPREFIX}stack_checker_report_usage} - Report Task Stack Usage
    2020@end itemize
     
    3636Recursive routines make calculating peak stack usage difficult, if not
    3737impossible.  Each call to the recursive routine consumes @i{n} bytes
    38 of stack space.  If the routine recursives 1000 times, then @code{1000 * @i{n}}
    39 bytes of stack space are required.
     38of stack space.  If the routine recursives 1000 times, then
     39@code{1000 * @i{n}} bytes of stack space are required.
    4040
    4141@subsection Execution
     
    4545indicate the stack is unused.  As the task executes, it will overwrite
    4646this pattern in memory.  At each task switch, the stack bounds checker's
    47 task switch extension is executed.  This extension checks that the last
    48 @code{n} bytes of the task's stack have not been overwritten.  If they
    49 have, then a blown stack error is reported.
     47task switch extension is executed.  This extension checks that:
     48
     49@itemize @bullet
     50
     51@item the last @code{n} bytes of the task's stack have
     52not been overwritten.  If this pattern has been damaged, it
     53indicates that at some point since this task was context
     54switch to the CPU, it has used too much stack space.
     55
     56@item the current stack pointer of the task is not within
     57the address range allocated for use as the task's stack.
     58
     59@end itemize
     60
     61If either of these conditions is detected, then a blown stack
     62error is reported using the @code{printk} routine.
    5063
    5164The number of bytes checked for an overwrite is processor family dependent.
     
    6881
    6982The stack checker is initialized automatically when its task
    70 create extension runs for the first time.  When this occurs,
    71 the @code{@value{DIRPREFIX}stack_checker_initialize} is invoked.
     83create extension runs for the first time.
    7284
    7385The application must include the stack bounds checker extension set
    7486in its set of Initial Extensions.  This set of extensions is
    75 defined as @code{STACK_CHECKER_EXTENSION}.  If using @code{<confdefs.h>}
     87defined as @code{STACK_CHECKER_EXTENSION}.  If using @code{<rtems/confdefs.h>}
    7688for Configuration Table generation, then all that is necessary is
    7789to define the macro @code{STACK_CHECKER_ON} before including
    78 @code{<confdefs.h>} as shown below:
     90@code{<rtems/confdefs.h>} as shown below:
    7991
    8092@example
     
    8294#define STACK_CHECKER_ON
    8395  ...
    84 #include <confdefs.h>
     96#include <rtems/confdefs.h>
    8597@end group
    8698@end example
    8799
     100@subsection Checking for Blown Task Stack
     101
     102The application may check whether the stack pointer of currently
     103executing task is within proper bounds at any time by calling
     104the @code{@value{DIRPREFIX}stack_checker_is_blown} method.  This
     105method return @code{FALSE} if the task is operating within its
     106stack bounds and has not damaged its pattern area.
     107
    88108@subsection Reporting Task Stack Usage
    89109
    90110The application may dynamically report the stack usage for every task
    91 in the system by calling the @code{@value{DIRPREFIX}stack_checker_report_usage} routine.
     111in the system by calling the
     112@code{@value{DIRPREFIX}stack_checker_report_usage} routine.
    92113This routine prints a table with the peak usage and stack size of
    93114every task in the system.  The following is an example of the
     
    111132
    112133When the stack bounds checker determines that a stack overflow has occurred,
    113 it will attempt to print a message identifying the task and then shut the
    114 system down.  If the stack overflow has caused corruption, then it is
    115 possible that the message can not be printed.
     134it will attempt to print a message using @code{printk} identifying the
     135task and then shut the system down.  If the stack overflow has caused
     136corruption, then it is possible that the message can not be printed.
    116137
    117138The following is an example of the output generated:
     
    136157and status codes.
    137158
     159
     160@c
     161@c  rtems_stack_checker_is_blown
     162@c
    138163@page
    139 @subsection stack_checker_initialize - Initialize the Stack Bounds Checker
     164@subsection stack_checker_is_blown - Has Current Task Blown Its Stack
    140165
    141166@subheading CALLING SEQUENCE:
     
    143168@ifset is-C
    144169@example
    145 void rtems_stack_checker_initialize( void );
     170boolean rtems_stack_checker_is_blown( void );
    146171@end example
    147172@end ifset
     
    153178@end ifset
    154179
    155 @subheading STATUS CODES: NONE
     180@subheading STATUS CODES:
     181@code{TRUE} - Stack is operating within its stack limits@*
     182@code{FALSE} - Current stack pointer is outside allocated area
     183
    156184
    157185@subheading DESCRIPTION:
    158186
    159 Initialize the stack bounds checker.
     187This method is used to determine if the current stack pointer
     188of the currently executing task is within bounds.
    160189
    161190@subheading NOTES:
    162191
    163 This is performed automatically the first time the stack bounds checker
    164 task create extension executes.
     192This method checks the current stack pointer against
     193the high and low addresses of the stack memory allocated when
     194the task was created and it looks for damage to the high water
     195mark pattern for the worst case usage of the task being called.
    165196
    166197@page
Note: See TracChangeset for help on using the changeset viewer.