home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The CDPD Public Domain Collection for CDTV 3
/
CDPDIII.bin
/
bbs
/
ff870.lha
/
StackCheck
/
StackCheck.doc
< prev
next >
Wrap
Text File
|
1993-05-05
|
10KB
|
251 lines
StackCheck 1.0
written by Günther Röhrich
this program is Public Domain
INTRODUCTION
StackCheck determines the maximum stack usage of a program. The method it uses
differs completely from all the other stack-watching programs like WatchStack or
Xoper.
This program is intended for developers who want to know the stack usage of
their programs.
ADVANTAGES
- StackCheck determines the real maximum stack usage and not the maximum
value of multiple measurements. Therefore even small peaks of stack usage
will be noticed. (A "small peak" means a stack usage with a duration of only
a few CPU cycles)
- StackCheck doesn't has to be active during the whole runtime of a program.
It's enough when it is active during the start and the finish of a program.
- Stack usage will be noticed even when multitasking is turned off by the
program which is beeing checked.
- For programs started from Workbench it is enough when StackCheck is active
short time before the program ends. This is enough to determine the maximum
stack usage correctly.
DISADVANTAGES
- Stack usage short time that occurs after beginning and before finish of a
program cannot be determined. ("short time" means about 0,04 seconds)
Exception: For programs started from Workbench stack usage that occured even
very short time after beginning will be determined correctly.
- With Kickstart 1.2/1.3 it is not possible to examine programs launched from
CLI/Shell. (see later)
- With Kickstart 2.0 or higher it is impossible to examine BCPL-programs.
(It will probably cause a system crash when trying to do that)
NEEDED COMPUTER AND OPERATING SYSTEM
StackCheck works on all AMIGAs with all Kickstart versions and with all
processors.
Tested configurations:
A500 Kickstart 2.04;1.3 Processor: 68000
A1200 Kickstart 3.00 Processor: 68EC020
A3000 Kickstart 2.04 Processor: 68030
USAGE OF STACKCHECK
The syntax of StackCheck is:
StackCheck Name|* [DELAY=n][PRI=n][STACK=n][NUM=n]
To abort StackCheck press CTRL-C.
Name
The name of the program you want to examine has to be given as the first
argument. This name is case-sensitive. If the name contains blanks it must be
put in quotation-marks.
The sign "*" stands for any name. Other wildcards are not supported.
All the other arguments are optional. If they are left out an internal default
value will be used. The letter n stands for a number.
(Example: stack=20000)
DELAY=n
n stands for the time period between two examinations of the stack. The unit
is 1/50 second. The default value is 2.
PRI=n
This will set the priority of the StackCheck task to n. The default value is 1.
STACK=n
StackCheck will only examine a program if its stack size is equal to n.
(This is useful if "*" is used for the name)
NUM=n
StackCheck will only examine a program if its CLI-number is equal to n. The
CLI-number is usually displayed in the CLI/Shell prompt.
(This is useful if "*" is used for the name)
STACKCHECK'S WORKING METHOD
Note: If you're not familiar on how the processor stack works please read the
chapter "How The Stack Works".
First of all, the unused area of the stack is filled with the pattern $BEEF.
If a program is using more stack the pattern will be overwritten. To determine
the maximum stack usage it's sufficient to count how large the undamaged area
still is. This measurement must be repeated because it's impossible to know
when the program will end. The only measurement that counts is the last one.
At the start of StackCheck it checks if the program already runs. If not it
waits a period and it checks again if the program has been started in the mean
time. (This period can be set with the DELAY-option)
If the program is found the first two words at the lower end of the stack will
be examined. If the fill pattern $BEEF is found nothing will be done. If they
contained zeros then the program must have been started from Workbench. At the
very beginning the complete stack area contained zeros. Therefore, all the zeros
beginning from the lower end of the stack will be replaced by the fill pattern
$BEEF. If a word is found that does not contain zero this will be stopped. This
is also the place of the maximum stack usage that occured so far. The filling
procedure will also be stopped when the actual stack pointer is reached. This
must be done to leave the program undamaged.
If the first two words at the lower end of the stack contained an unknown
pattern then the free stack area up to the actual stack pointer will be filled
with the pattern $BEEF. This is the case if the program has been started from
CLI/Shell. Then it is impossible to determine the maximum stack usage that
occured before the filling process.
After this preliminary work StackCheck will determine how far the pattern
$BEEF remaines undamaged. This marks the place of the maximum stack usage
that occured so far. This procedure will stop if CTRL-C is pressed or the
program ends. (The delay between two examinations can be set with the
DELAY-option.)
When StackCheck is stopped the results of the last measurement will be
printed. The results of the other measurements are not needed. Therefore it is
not necessary to let StackCheck do its measurements during the whole runtime
of the program.
If you know when the program ends it is recommended to stop StackCheck by
pressing CTRL-C right after the program has been started. Short time before
the program ends you must launch StackCheck again. When the program ends you
will get the same results as when StackCheck was active all the time.
With programs started from Workbench it is enough when StackCheck was active
before the program finishes. However, it is recommended to activate StackCheck
at the beginning of the program so that the zeros will be replaced by the more
reliable pattern $BEEF.
ANALYSING THE OUTPUT OF STACKCHECK
A typical output of StackCheck looks like this:
StackCheck V1.0 by Günther Röhrich
This program is Public Domain. Press CTRL-C to abort.
Free stack area contained unknown pattern:
00290F58: 000A3EDF 00000FA0 00292454 00000001
Stack OK:
00290F58: BEEFBEEF BEEFBEEF BEEFBEEF BEEFBEEF
Stacksize: 4000
Used max: 2818
First of all the first 16 bytes beginning from the lower end of the stack
will be printed. This is the status as found by StackCheck. The number before
the colon is the address of the lower end of the stack. Then the same area
is printed again as it looked at the last examination of the stack. If a stack
overflow occured a warning message will be printed. It is impossible to detect
how much the stack overflowed. Then the stacksize and the maximum stack usage
will be printed.
If StackCheck detects that another stack area outside of the normal area has
been used it will display a corresponding message. It is possible for example by
using exec's StackSwap() function. This cannot always be detected.
PROBLEMS
At the beginning I mentioned that the stack usage short time after the start
and short time before the end of a program cannot be determined. If somebody
writes a program it is recommended to insert a short delay as the first and
last command in the program. (for example with the command Delay(50))
Of course, it is better wenn the start and finish of the program has an inter-
action with the user.
As mentioned before it is not possible to examine programs started from
CLI/Shell under Kickstart 1.2/1.3. To avoid system crashes it is recommended
to use only programs started from Workbench.
Under Kickstart 2.0 or higher it is impossible to examine BCPL programs because
this will crash your system. In this case some memory is used in the free stack
area. This area will be overwritten with the pattern $BEEF. BCPL programs are
normally not used with Kickstart 2.0 or higher, therefore I haven't done
anything against this.
If programs are using the free stack area for any purpose (for example to detect
a stack overflow by themselves) some problems may occur. Please contact me if
you have such a program. (I dont't have one)
When a program is launched several times it is possible that StackCheck reports
slightly different values for the maximum stack usage, even when the program
performs the same activities every time. This is not StackCheck's fault. It
depends on the moment when the program is interrupted by task-switching or
interrupts. (In this case about 70 bytes will be stored on the stack.)
HOW THE STACK WORKS
This chapter is intended for those who are not familiar on how the stack works.
For all the other there is no need to read it.
The processor stack of the MC680x0 grows from higher addresses towards lower
addresses. The register A7 is used as a stack pointer. It points at the last
address of the last item on the stack. To avoid address errors A7 is kept word
aligned. For compatibility reasons this is the same on the 68020 or higher
although these processors don't have address errors.
The stack itself may have any size, the system does not check if the stack goes
beyond the limits. (With a MMU it could be possible)
The stack is used to store temporary variables and return addresses at function
calls. When an interrupt occurs the state of the processor is also stored on the
stack to allow the program to be continued.
The AMIGA stores the stack pointer at an interruption of a program in the
variable SPReg of the task structure. The variables SPUpper and SPLower contain
the upper and lower end of the stack. (This is not always the case when
Kickstart 1.2/1.3 is used.)
ADDRESS OF THE AUTHOR AND OTHER NOTES
StackCheck is Public Domain, therefore you can do what you want with it. To
avoid confusions among the users please contact me if you want to distribute
a modified version.
If you find a bug please let me know about it. I am also happy if somebody sends
me a corrected version of the English documentation. (As you can see my English
is not very good)
Address:
Günther Röhrich
Lerchenbergstr. 4
W-7300 Esslingen
Germany
New address beginning from 1. July 1993:
Günther Röhrich
Lerchenbergstr. 4
73733 Esslingen
Germany