Microsoft Windows NT Call Profiler README File March 06, 1992 September 22, 1992 1. Description: ---------------- Windows NT (32-bit) Call/Attributive Profiler (CAP) for ix86 platform. 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. 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 pausing profiling at any time. o capsetup.exe -- Allows attaching/detaching cap.dll to/from all Windows applications. o readme -- Call Profiler readme document (this file). 3. Using the Call Profiler: ---------------------------- o Place CAP.INI in the root directory of C: drive and list all the DLL/EXE images to be profiled as follows: [EXES] Name of applications to be profiled. Each name should be on a new line. [PATCH IMPORTS] List of DLLs/EXEs to be patched for all of their imported entries. Each name should be on a new line. [PATCH CALLERS] List of DLLs to be profiled if called from the application or any of its DLLs. Each name should be on a new line. o Attach CAP.DLL to the application process. This can be done in two ways: 1) Recompile your EXE/DLL using the "-Gp" and "-Zd" compiler options. Link it with CAP.LIB using the "-debugtype:coff" and "-debug:partial" linker options. This method will cause all the functions in the recompiled sources to be profiled. 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. o Place CAP.DLL in your SYSTEM directory (i.e. ..\nt\system). o Run the application. 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 Measurment Methods: ---------------------------------------------- Suppose we have .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] 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] o Both ZOOMAN.EXE and HUNTED.EXE will be profiled for all the calls within WATER.DLL. c) Measuring calls from HUNTED.EXE to it's DLLs: o Put "AppInit_DLLs=CAP.DLL" under [windows] section of WIN.INI and reboot the system. o Setup CAP.INI as follows: [EXES] hunted.exe [PATCH IMPORTS] hunted.exe [PATCH CALLERS] o All calls from HUNTED.EXE to ELEPHANT.DLL, MONKEY.DLL, and SNAKE.DLL will be profiled. d) Measuring calls from ELEPHANT.DLL and MONKEY.DLL to their DLLs: o Put "AppInit_DLLs=CAP.DLL" under [windows] section of WIN.INI and reboot the system. o Setup CAP.INI as follows: [EXES] hunted.exe [PATCH IMPORTS] elephant.dll monkey.dll [PATCH CALLERS] o All calls from ELEPHANT.DLL and MONKEY.DLL to WATER.DLL and FOOD.DLL will be measured. e) Measuring all the calls to FOOD.DLL: o Put "AppInit_DLLs=CAP.DLL" under [windows] section of WIN.INI and reboot the system. o Setup CAP.INI as follows: [EXES] zooman.exe hunted.exe [PATCH IMPORTS] [PATCH CALLERS] food.dll o Both ZOOMAN.EXE and HUNTED.EXE will be profiled separately for all the calls to FOOD.DLL. For HUNTED.EXE all the calls from both ELEPAHND.DLL and MONKEY.DLL to FOOD.DLL will be profiled. 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] c+d) Measuring calls from HUNTED.EXE to it's DLLs and calls from ELEPHANT and MONKEY DLLs to their DLLs: o Put "AppInit_DLLs=CAP.DLL" under [windows] section of WIN.INI and reboot the system. o Setup CAP.INI as follows: [EXES] hunted.exe [PATCH IMPORTS] hunted.exe elephant.dll monkey.dll [PATCH CALLERS] 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] 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] * * * * * * * * * * * * * * * * 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] o Note that in addition to measuring calls within WATER.DLL, all the calls from ZOOMAN.EXE to WATER.DLL are measured. This is not supported and will cause unexpected behavior. 5. Exported Routines: ---------------------- These 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 exsiting profiling data and restart // profiling. .. .. // application's code .. StopCAP(); // Stop profiling without dumping data. DumpCAP(); // Dump profiling data to FOO.CAP file. 6. Profiling Data: ------------------- o Profiling data is 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 extention will be the data file name. See section 7 "Using CapDump" for more details. 3) Using exported routine DumpCAP(). Application name with .CAP extention 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 every time a dump is performed. 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 - 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) 7. Using CapDump: ------------------ o CapDump.exe can be used to pause profiling and clear/dump profiling data for all the applications being profiled, at any time. o The following options are available via CapDump.exe: - Pause : Stops profiling (applications continue to run). - Clear and Restart : Clears any existing profiling data and restarts profiling. - Dump and Pause : 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. 8. Using CapSetup: ------------------- Usage: CapSetup -A | -D -A Attaches CAP.dll to all Windows applications -D Detaches CAP.dll from all Windows applications Note: System needs to be rebooted in order for the change to take effect. 9. Caveats: ------------ o Call profiler is an ix86 only DLL. o If symbols are not available in an EXE/DLL that is being profiled, ??? is displayed as the function name. ** END OF README **