638 lines
22 KiB
Plaintext
638 lines
22 KiB
Plaintext
|
|
Microsoft Windows NT Call Profiler README File
|
|
|
|
March 06, 1992
|
|
September 22, 1992
|
|
February 22, 1993
|
|
April 27, 1994
|
|
|
|
|
|
|
|
1. Description:
|
|
----------------
|
|
|
|
Windows NT (32-bit) Call/Attributive Profiler (CAP) for x86, Mips,
|
|
Alpha, and PowerPC platforms.
|
|
|
|
CAP is a general purpose profiling tool that can be used to measure
|
|
the function call performance of .EXE's and .DLL's, (AKA modules),
|
|
in a variety of ways. The following measurement methods are
|
|
supported:
|
|
|
|
a) Measuring calls from within an .EXE.
|
|
|
|
b) Measuring calls from within a .DLL.
|
|
|
|
c) Measuring calls from an .EXE to all of it's DLLs.
|
|
|
|
d) Measuring calls from one .DLL to all of its DLLs.
|
|
|
|
e) Measuring all the calls to specified .DLL's, from
|
|
any .EXE or .DLL.
|
|
|
|
f) Any arbitrary combination of a) through e).
|
|
|
|
CAP creates a call tree of all the functions called in the EXE(s)/
|
|
DLL(s) being profiled.
|
|
|
|
Profiling Data can be collected only for functions in C programs by
|
|
using the attributed profiling hook provided by the Microsoft C
|
|
compiler (compiling with the "-Gh" option). Data is *NOT* collected
|
|
for functions in assembler language programs.
|
|
|
|
|
|
|
|
2. Profiling Files:
|
|
--------------------
|
|
|
|
o cap.ini -- Call Profiler initialization file.
|
|
o cap.dll -- Call Profiler DLL.
|
|
o cap.lib -- Profiler library file containing profiling entry
|
|
points.
|
|
o capdump.exe -- Dump utility for dumping/clearing profiling
|
|
data, and stopping profiling at any time.
|
|
o capsetup.exe -- Allows attaching/detaching cap.dll to/from all
|
|
Windows applications.
|
|
o penter.lib -- An empty library containing a dummy CAP entry point.
|
|
This can be used instead of CAP.lib to link with an
|
|
already CAP ready executable object modules
|
|
(recompiled with the -Gh option) so the application
|
|
can run without recompiling and without any of the
|
|
CAP overheads.
|
|
o sol.end -- A sample CAP data file generated by a sample
|
|
profile run of sol.exe.
|
|
o readme -- Call Profiler README document (this file).
|
|
|
|
|
|
|
|
3. Using the Call Profiler:
|
|
----------------------------
|
|
|
|
|
|
|
|
o Place a copy of CAP.INI in one of the following area where it
|
|
suits your need:
|
|
- the CURRENT directory
|
|
- the Windows directory (ie: c:\windows\cap.ini)
|
|
- the root of the current drive (\cap.ini)
|
|
- the root dir of C: drive (c:\cap.ini)
|
|
|
|
list all the DLL/EXE images to be profiled as follows:
|
|
|
|
(Note: CAP.INI and all its three section headers must exist but the
|
|
sections could be left blank)
|
|
|
|
[EXES]
|
|
Name of applications to be profiled. Each name should be on a
|
|
new line.
|
|
|
|
[PATCH IMPORTS]
|
|
List of DLLs/EXEs to be profiled for all of their imported entries.
|
|
Each name should be on a new line.
|
|
|
|
[PATCH CALLERS]
|
|
List of DLLs to be profiled for their exported entries if called
|
|
from the applications (listed in the [EXE] section) or any of their
|
|
DLLs. Each name should be on a new line.
|
|
|
|
[NAME LENGTH]
|
|
This is an optional section allowing to specify the maximum number of
|
|
characters to be printed for the routine name in the output data
|
|
files. If the value is not specified or 0, default length of 40 is
|
|
used. Length can be any value between 20 and 2048.
|
|
|
|
[CHRONO FUNCS]
|
|
List of modules and corresponding functions that start the dump
|
|
of the chronological listing. For example, if "test=SomeFunc" is
|
|
listed under this section then all functions that are called
|
|
inside of test!SomeFunc... will be listed until the call depth
|
|
is less than or equal to the depth of the listed function.
|
|
|
|
[EXCLUDE FUNCS]
|
|
List of modules and corresponding functions that will be excluded
|
|
from the profiling process. The [call _penter] at the beginning
|
|
of the function will be NOPed. But if these functions call
|
|
some other functions and if these children functions are not listed
|
|
under this section, they will still be included in the profiling
|
|
process. To correctly take a function out of the profiling
|
|
process, him and his children must all be included under this
|
|
section. If not, the timing of the Excluded function will be
|
|
included with its parent routine while the timing of its children
|
|
routine will still be computed separately.
|
|
|
|
[OUTPUT FILE]
|
|
filename=xxxxx
|
|
This option allows the user to specify a different drive for the
|
|
output listing. This file can be over the net somewhere or just
|
|
a different name than xxxx.END or xxxx.CAP. For example:
|
|
filename=c:\results\explorer\explorer.cap or
|
|
filename=\\Results\CAP\explorer\explorer.pro
|
|
|
|
[CAP FLAGS]
|
|
- profile
|
|
"on" or "off". Turn on or off profiling initially without
|
|
altering the code.
|
|
- dumpbinary
|
|
"on" or "off". This is to allow the dumping of the data in binary form,
|
|
not in the regular text form. This feature is there to allow faster
|
|
dumping and require less space. A program called CAPRPT will go in and
|
|
produce the listing from this data. CAPRPT is still under development.
|
|
- capthread
|
|
"on" or "off". If on, this switch will start the 3 threads that will
|
|
interact with CAPDUMP to Clear, Start and Stop the collection of data.
|
|
This is made into an option so if the user does not need CAPDUMP, he/she
|
|
does not have to start 3 additional threads everytime CAP is initialized.
|
|
This is quite expensive when profiling a number of processes at the same
|
|
time.
|
|
- loadlibrary
|
|
"on" or "off". If on, CAP will intercept all LoadLibrary calls from the
|
|
profiled binary and correctly initializes its symbol table.
|
|
- setjump
|
|
"on" or "off". If on, CAP will also intercept longjmp instructions and
|
|
handled it accordingly.
|
|
- undecoratename
|
|
"on" or "off". Turn on or off the undecoration of function
|
|
names.
|
|
- excelaware
|
|
"on" or "off". Turn on or off the addition of delimiters so
|
|
the output listing can be imported into Excel.
|
|
- regular dump
|
|
"on" or "off". Turn on or off the regular data that CAP dumps out.
|
|
This is to shorten the output listing if you are only interested in
|
|
the chronological listings.
|
|
- chronocollect
|
|
"on" or "off". Turn on or off the collection of the chronological
|
|
listing of the functions. This could be very lengthy.
|
|
- chronodump
|
|
"on" or "off". Turn on or off the output for the chrono listing.
|
|
This switch is independent of [chronocollect] since sometimes you
|
|
just want to turn off the dumping but leaving the collection alone.
|
|
- slowsymbols
|
|
"on" or "off". Turn on or off exhaustive lookup of symbols. If
|
|
off, addresses for which symbols cannot be quickly found (e.g.
|
|
static symbols) are printed as absolute addresses versus a symbol
|
|
plus offset in the on case.
|
|
|
|
o Attach CAP.DLL to the application process. This can be done in two
|
|
ways:
|
|
|
|
1) Recompile your EXE/DLL using the "-Gh" and "-Zd" compiler
|
|
options. (NOTE - on Mips platform, use "-Od" to disable
|
|
compiler optimization.)
|
|
|
|
Link it with CAP.LIB using the "-debugtype:coff" and
|
|
"-debug:mapped,partial" linker options.
|
|
|
|
This method will cause all the C functions in the recompiled
|
|
sources to be profiled.
|
|
|
|
NOTE:- If symbols have been removed from your exe
|
|
or dll, Cap will try to locate the symbols files (DBG
|
|
files) using the path as specified in the environment
|
|
variable "_nt_symbol_path".
|
|
E.G. if the DBG file of your exe is in c:\symbols\exe, set
|
|
_nt_symbol_path to c:\symbols.
|
|
|
|
2) Run CapSetup.exe to attach CAP.DLL to all Windows applications.
|
|
Note that only those EXEs listed in the [EXES] section of
|
|
CAP.INI will be profiled. Overhead for the non-profiled
|
|
applications is minimal. See section 8, "Using CapSetup",
|
|
for CapSetup.exe usage. You need to have Administrative
|
|
privileges in order to run CapSetup.
|
|
|
|
*** Please be extremely careful with this option since turning
|
|
*** it on could resulted in the system being totally thrashed
|
|
*** if CAP.DLL could not run correctly. Thus causing the
|
|
*** profiled binary to fail to load also. And if the binary
|
|
*** is as important as WINLOGON, then the only thing to do
|
|
*** is to reload NT or use a dummy cap.dll or remove the
|
|
*** CAP.INI file.
|
|
|
|
|
|
o Place CAP.DLL in your SYSTEM directory (i.e. ..\nt\system32).
|
|
|
|
o Run your applications.
|
|
|
|
o All the applications specified in the [EXES] section of the CAP.INI
|
|
will be profiled.
|
|
|
|
o Exit the application to dump the profiling data, or run CapDump.exe
|
|
to dump the data. See section 6 "Profiling Data" for details.
|
|
|
|
|
|
|
|
4. Examples for Supported Measurement Methods:
|
|
----------------------------------------------
|
|
|
|
Suppose we have Windows .EXE's called ZOOMAN and HUNTED, and .DLLs
|
|
called ELEPHANT, MONKEY, SNAKE, WATER, and FOOD. Let's assume the
|
|
following intercall dependencies exist:
|
|
|
|
zooman.exe
|
|
- water.dll
|
|
- food.dll
|
|
|
|
hunted.exe
|
|
- elephant.dll
|
|
-- water.dll
|
|
-- food.dll
|
|
- monkey.dll
|
|
-- water.dll
|
|
-- food.dll
|
|
- snake.dll
|
|
|
|
|
|
|
|
a) Measuring calls from within ZOOMAN.EXE:
|
|
|
|
o Recompile ZOOMAN and link it with CAP.LIB as described in
|
|
section 3.
|
|
|
|
o Setup CAP.INI as follows:
|
|
|
|
[EXES]
|
|
zooman.exe
|
|
|
|
[PATCH IMPORTS]
|
|
|
|
[PATCH CALLERS]
|
|
|
|
[NAME LENGTH]
|
|
60
|
|
|
|
o All the C functions in ZOOMAN.EXE will be profiled by CAP.
|
|
|
|
|
|
|
|
b) Measuring calls from within WATER.DLL:
|
|
|
|
o Recompile WATER and link it with CAP.LIB as described in
|
|
section 3.
|
|
|
|
o Setup CAP.INI as follows:
|
|
|
|
[EXES]
|
|
zooman.exe
|
|
hunted.exe
|
|
|
|
[PATCH IMPORTS]
|
|
|
|
[PATCH CALLERS]
|
|
|
|
[NAME LENGTH]
|
|
|
|
o Both ZOOMAN.EXE and HUNTED.EXE will be profiled for all the
|
|
C functions within WATER.DLL.
|
|
|
|
|
|
|
|
c) Measuring calls from HUNTED.EXE to it's DLLs:
|
|
|
|
o Run CapSetup.exe to attach cap.dll to all Windows Applications,
|
|
and reboot the system.
|
|
|
|
o Setup CAP.INI as follows:
|
|
|
|
[EXES]
|
|
hunted.exe
|
|
|
|
[PATCH IMPORTS]
|
|
hunted.exe
|
|
|
|
[PATCH CALLERS]
|
|
|
|
[NAME LENGTH]
|
|
|
|
o All the calls from HUNTED.EXE to ELEPHANT.DLL, MONKEY.DLL,
|
|
and SNAKE.DLL will be profiled. These are all the C functions
|
|
exported by ELEPHANT, MONKEY, and SNAKE DLLs which are used
|
|
by HUNTED.exe.
|
|
|
|
|
|
|
|
d) Measuring calls from ELEPHANT.DLL and MONKEY.DLL to their DLLs:
|
|
|
|
o Run CapSetup.exe to attach cap.dll to all Windows Applications,
|
|
and reboot the system.
|
|
|
|
o Setup CAP.INI as follows:
|
|
|
|
[EXES]
|
|
hunted.exe
|
|
|
|
[PATCH IMPORTS]
|
|
elephant.dll
|
|
monkey.dll
|
|
|
|
[PATCH CALLERS]
|
|
|
|
[NAME LENGTH]
|
|
|
|
o All calls from ELEPHANT.DLL and MONKEY.DLL to WATER.DLL and
|
|
FOOD.DLL will be measured. These are all the C functions
|
|
exported by WATER and FOOD DLLs which are used by either
|
|
ELEPHANT.DLL or MONKEY.DLL.
|
|
|
|
|
|
|
|
e) Measuring all the calls to FOOD.DLL:
|
|
|
|
o Run CapSetup.exe to attach cap.dll to all Windows Applications,
|
|
and reboot the system.
|
|
|
|
o Setup CAP.INI as follows:
|
|
|
|
[EXES]
|
|
zooman.exe
|
|
hunted.exe
|
|
|
|
[PATCH IMPORTS]
|
|
|
|
[PATCH CALLERS]
|
|
food.dll
|
|
|
|
[NAME LENGTH]
|
|
|
|
o Both ZOOMAN.EXE and HUNTED.EXE will be profiled separately for
|
|
all the calls to FOOD.DLL. For ZOOMAN.EXE, these are all the
|
|
C functions exported by FOOD.DLL which are used by ZOOMAN.EXE.
|
|
And for HUNTED.EXE these are all the C functions exported by
|
|
FODD.DLL which are used by either ELEPAHNT.DLL or MONKEY.DLL.
|
|
|
|
|
|
f) Any arbitrary combination of a) through e):
|
|
|
|
a+c) Measuring calls from within ZOOMAN.EXE and calls to it's DLLs:
|
|
|
|
o Recompile ZOOMAN and link it with CAP.LIB as described in
|
|
section 3.
|
|
|
|
o Setup CAP.INI as follows:
|
|
|
|
[EXES]
|
|
zooman.exe
|
|
|
|
[PATCH IMPORTS]
|
|
zooman.exe
|
|
|
|
[PATCH CALLERS]
|
|
|
|
[NAME LENGTH]
|
|
|
|
|
|
c+d) Measuring calls from HUNTED.EXE to it's DLLs and calls from
|
|
ELEPHANT and MONKEY DLLs to their DLLs:
|
|
|
|
o Run CapSetup.exe to attach cap.dll to all Windows Applications,
|
|
and reboot the system.
|
|
|
|
o Setup CAP.INI as follows:
|
|
|
|
[EXES]
|
|
hunted.exe
|
|
|
|
[PATCH IMPORTS]
|
|
hunted.exe
|
|
elephant.dll
|
|
monkey.dll
|
|
|
|
[PATCH CALLERS]
|
|
|
|
[NAME LENGTH]
|
|
|
|
|
|
a+c+d) Measuring calls from within HUNTED.EXE and calls to its DLLs
|
|
plus calls from ELEPHANT and MONKEY DLLs to their DLLs:
|
|
|
|
o Recompile HUNTED and link it with CAP.LIB as described in
|
|
section 3.
|
|
|
|
o Setup CAP.INI as follows:
|
|
|
|
[EXES]
|
|
hunted.exe
|
|
|
|
[PATCH IMPORTS]
|
|
hunted.exe
|
|
elephant.dll
|
|
monkey.dll
|
|
|
|
[PATCH CALLERS]
|
|
|
|
[NAME LENGTH]
|
|
|
|
|
|
b+d) Measuring calls from within ELEPHANT.DLL and calls to its DLLs:
|
|
|
|
o Recompile ELEPHANT and link it with CAP.LIB as described in
|
|
section 3.
|
|
|
|
o Setup CAP.INI as follows:
|
|
|
|
[EXES]
|
|
hunted.exe
|
|
|
|
[PATCH IMPORTS]
|
|
elephant.dll
|
|
|
|
[PATCH CALLERS]
|
|
|
|
[NAME LENGTH]
|
|
|
|
|
|
* * * * * * * * * * * * *
|
|
* * * R E S T R I C T I O N * * *
|
|
* * * * * * * * * * * * *
|
|
|
|
Do NOT measure calls within a DLL if the DLL's exported functions
|
|
are being measured from another EXE/DLL. The following example shows
|
|
this incorrect combination which should be avoided:
|
|
|
|
x) Measuring calls from ZOOMAN.EXE to its DLLs and calls within
|
|
WATER.DLL:
|
|
|
|
o Recompile WATER and link it with CAP.LIB as described in
|
|
section 3.
|
|
|
|
o Setup CAP.INI as follows:
|
|
|
|
[EXES]
|
|
zooman.exe
|
|
|
|
[PATCH IMPORTS]
|
|
zooman.exe
|
|
|
|
[PATCH CALLERS]
|
|
|
|
[NAME LENGTH]
|
|
|
|
o Note that in addition to measuring all C functions (including the
|
|
exported routines) within WATER.DLL, all the C functions exported
|
|
by WATER.DLL which are used by ZOOMAN.EXE are measured. This
|
|
means that the same function within WATER.DLL will be measured
|
|
twice. These types of scenarios are not supported and will result
|
|
in unexpected behavior.
|
|
|
|
|
|
|
|
|
|
5. Exported Routines:
|
|
----------------------
|
|
|
|
The exported entry points listed below can be used to control
|
|
profiling certain sections of code. They can be combined with
|
|
any of the supported measurement methods mentioned above.
|
|
|
|
o StartCAP() : Clears profiling data & starts profiling
|
|
o StopCAP() : Stops profiling
|
|
o DumpCAP() : Dumps data for the current CAP.DLL instance
|
|
|
|
A typical example (foo.exe):
|
|
|
|
StartCAP(); // Clear existing profiling data and restart
|
|
// profiling.
|
|
..
|
|
.. // application's code
|
|
..
|
|
|
|
StopCAP(); // Stop profiling without dumping data.
|
|
DumpCAP(); // Dump profiling data to FOO.CAP file.
|
|
|
|
Prototypes for these routines are:
|
|
|
|
extern void _stdcall StartCAP(void);
|
|
extern void _stdcall StopCAP(void);
|
|
extern void _stdcall DumpCAP(void);
|
|
|
|
|
|
6. Profiling Data:
|
|
-------------------
|
|
|
|
o Profiling data can be captured in three ways:
|
|
|
|
1) Upon termination of the application profiling data is dumped
|
|
into a text file using the application name with .END
|
|
extension.
|
|
|
|
2) Using the dump utility, CapDump.exe, profiling data can be
|
|
dumped at any time. Application name with .CAP extension will
|
|
be the data file name. See section 7 "Using CapDump" for more
|
|
details.
|
|
|
|
3) Using exported routine DumpCAP(). Application name with .CAP
|
|
extension will be the data file name.
|
|
|
|
|
|
o Data files are created in the same directory as the application
|
|
that is being profiled.
|
|
|
|
o Data is appended to data files with each data dump.
|
|
|
|
o A separate call tree is generated for each thread in the process
|
|
context. Different sections in the data file indicates data for
|
|
different threads in the process.
|
|
|
|
o The following data is dumped:
|
|
|
|
- Call depth in the tree
|
|
- Function name
|
|
- Number of calls
|
|
- Total time for the function+callees
|
|
- Time per call for the function+callees
|
|
- Total time of the function only
|
|
- Time per call of the function only
|
|
- First time (function+callees)
|
|
- Minimum time (function+callees)
|
|
- Maximum time (function+callees)
|
|
|
|
o See SOL.END as a sample output file.
|
|
|
|
|
|
|
|
7. Using CapDump:
|
|
------------------
|
|
|
|
o CapDump.exe can be used to stop profiling and clear/dump
|
|
profiling data for all the applications being profiled, at
|
|
any time.
|
|
|
|
o The following options are available via CapDump.exe:
|
|
|
|
- Stop : Stops profiling (applications continue to run).
|
|
|
|
- Clear and Restart : Clears any existing profiling data and
|
|
restarts profiling.
|
|
|
|
- Dump and Stop : Dumps any existing profiling data and stops
|
|
profiling (applications continue to run).
|
|
|
|
o Data is dumped to a text file using the profiling applications name
|
|
with .CAP extension. All fields are tab separated. Data is
|
|
appended to data files with each dump.
|
|
|
|
o If calls are being profiled when data clearing is requested,
|
|
the time of clearing is used as the starting time for those
|
|
calls.
|
|
|
|
o A log file, capdump.log, is generated when capdump.exe is run. It
|
|
will contain any errors that might occur during capdump.exe operation
|
|
and for normal error free operation, capdump.log will be empty.
|
|
|
|
|
|
|
|
8. Using CapSetup:
|
|
-------------------
|
|
|
|
Usage: CapSetup -A | -D
|
|
|
|
-A Attaches CAP.dll to all Windows applications
|
|
-D Detaches CAP.dll from all Windows applications
|
|
|
|
Notes: 1) Administrative privileges are required in order to run
|
|
CapSetup.
|
|
2) System needs to be rebooted in order for the change to
|
|
take effect.
|
|
|
|
*** Please be extremely careful with this option since turning
|
|
*** it on could resulted in the system being totally thrashed
|
|
*** if CAP.DLL could not run correctly. Thus causing the
|
|
*** profiled binary to fail to load also. And if the binary
|
|
*** is as important as WINLOGON, then the only thing to do
|
|
*** is to reload NT or use a dummy cap.dll, or remove
|
|
*** the CAP.INI file.
|
|
|
|
9. Caveats:
|
|
------------
|
|
|
|
o Cap - if a routine being profiled is within try-except
|
|
block and it crashes, the stack will NOT unwind. This is because
|
|
there is no prolog code in the Cap penter to support this.
|
|
|
|
o For Mips only - Mips Cap cannot profile static functions.
|
|
|
|
o If symbols are not available in an EXE/DLL that is being profiled,
|
|
??? is displayed as the function name.
|
|
|
|
o Non-local GOTOs (i.e. setjmp/longjmp calls) are not currently
|
|
supported. Profiling an application containing any non-local GOTOs
|
|
will result in unexpected results.
|
|
|
|
o Profiling data in *NOT* collected for functions in assembler
|
|
language programs.
|
|
|
|
o Paging file size will increase while profiling.
|
|
|
|
o For Alpha only - setjump, loadlibrary, and Exclude Funcs are not
|
|
implemented in this release.
|
|
|
|
o It may take a long time when cap is dumping data to the
|
|
cap file. In some cases, it may take up to 30 minutes,
|
|
depending on how many symbols and the level of nesting
|
|
calls.
|
|
|
|
o If you are using GDI calls, you may want to add GdiSetBatchLimit(1)
|
|
for each thread before you re-compile with cap.lib. This is to disable
|
|
batching so each GDI call will be performed and profiled correctly.
|
|
|
|
** END OF README **
|