DIGITAL Continuous Profiling Infrastructure for Windows NT (TM) version V1.1 Copyright (C) 1996, 1997 DIGITAL Equipment Corporation This is the README.TXT file for the Windows NT version of DCPI. ------------------------------------------------------------------------------ Upgrade Instructions ------------------------------------------------------------------------------ When upgrading or reinstalling DCPI, it is best to remove the old version before installing the new version. To uninstall an old release: * Stop the DCPI Daemon. Use the DCPI control panel, or type "NET STOP DCPISVC" in a coommand prompt window. * Remove DCPI programs. Go into the Windows NT Control Panel, run "Add/Remove Programs", choose "Digital Continuous Profiling", and then click "Remove." Now, follow the installation instructions below: ------------------------------------------------------------------------------ Installation Instructions ------------------------------------------------------------------------------ * To install DCPI for Windows NT, you will need the following: Alpha AXP processor (EV4, EV45, EV5, or EV56) Windows NT 4.0 FREE BUILD (any service pack level) At least 20MB free disk space At least 5MB free memory Administrator Privileges on the local system. Note: DCPI does not work on the checked build of NT. We're currently investigating this. * Unpack the kit using PKZIP(tm), WinZIP(tm), or other similar archive unacking software. Run the installation program SETUP.EXE which can be found inside the .ZIP file. The SETUP utility will ask you where to place the installed kit files. Choose a directory with sufficient space (the default is \DCPI on your system disk). DCPI SETUP will install the software, create some program icons for the control panel applet and release notes, then ask you to reboot your system to complete the installation of the device driver. By default, the following directory tree is created: \DCPI Main directory containing release notes and uninstall information. The DCPI Daemon's log file is created here. \DPCI\BIN Program binaries. You can add this directory to your search path. \DCPI\HELP HTML files containing the Unix HELP files. (Windows NT specific help files are in progress). \DCPI\DB Database files. DCPI for Windows NT is uninstallable by using the NT control panel. Select 'Settings' from the start menu, then 'Control Panel', and then 'Add/Remove Programs'. Choose DCPI from the list of installed programs and click "Install/Remove", and DCPI will be removed from your system. * To provide profiles of Kernel code, it is very useful to install the symbols to your system disk. These files are usually found on the SUPPORT\DEBUG\SYMBOLS\ALPHA directory of the CD, but you may need to obtain them from Microsoft's web site if you have installed any of the NT Service Packs. To install the symbols, XCOPY the symbol tree to your system root: XCOPY Q:\SUPPORT\DEBUG\SYMBOLS\ALPHA\*.* %SystemRoot%\SYMBOLS\*.* /S Then, add a system-wide environment variable to help DCPI and other NT tools find the symbols: _NT_SYMBOL_PATH=%SystemRoot%\SYMBOLS Environment variables are added by going to the property sheet (right button menu) of "My Computer". ------------------------------------------------------------------------------- Starting DCPI ------------------------------------------------------------------------------- * Run the DPCI "control panel" applet (DCPICPL.EXE) and select the events you want to monitor, and any other options for the daemon (you'll notice they are very similar to the Unix version). Note that you can select more than one event per counter. If you do this, DCPI will "multiplex" the different events, reducing the effective sampling rate for the counter. If you multiplex events, counter #0 must always be set to measure 'cycles', since the cycle counter interrupts are used to control the multiplexing of the other counters. When you click OK to exit the dialog, these options will be saved in the registry. * After selecting the counters and other options, go to the 'Start' tab in the control panel and press the "Start Sampling" button. The NT Service Control Manager should then start the DPCI Daemon. As an alternative, you can start and stop DCPI from the Command Prompt window by using the "NET START DCPISVC" and "NET STOP DCPISVC" commands. * To view the log file, stop the sampling process and press the "View Log" button on the 'Start' tab in the control panel. ------------------------------------------------------------------------------- Basic Procedures ------------------------------------------------------------------------------- Once DCPI is running, you can follow these basic procedures to get an overview of where the time is being spent: * Run an application whose performance you wish to monitor. This works best on applications that have symbolic information in the executable images, but you can use any image. * On the DCPI Control Panel, press the "Flush Samples" button, or run the "dcpiflush" command. This command extracts any unread samples from the driver and merges them with the profiles already stored on the disk. * Use the command "DCPIPROF -i" to get a listing of active images and the total samples collected for each image. * Use the command "DCPIPROF " to get a list of procedures within the image and the sample counts for each procedure. * Use the command "DCPILIST -asm -p " to display a disassembled procedure with sample counts and calculated CPI information for each instruction in a procedure. ------------------------------------------------------------------------------- DCPI Utilities Included ------------------------------------------------------------------------------- The following DCPI utilities have been ported to Windows NT: dcpisvc Continuous profiling daemon. Extracts raw samples from kernel device driver, associates them with executable images, and stores them in profiles on disk. This service can be started and stopped from the control panel, or by typing "net start|stop dcpisvc" dcpiprof Analyzes profile data collected by dcpisvc. Produces a breakdown of cpu time by image, or by procedures within images. dcpilist List the contents of a procedure and annotate the listing with samples collected during profiling via dcpid. The listing can contain either machine instructions, or source lines, or both. The listing is annotated with the samples collected during profiling, as well as the average number of cycles required to execute each instruction or source line. dcpicalc Annotates each instruction in a procedure's basic-block graph with the average number of cycles for that instruction, and computes the overall average cycle-per-instruction for that procedure. dcpix Measure execution frequencies for basic blocks and control-flow edges directly; output can be used by dcpicalc instead of estimating frequencies from sample counts. dcpisumxct Aggregates execution counts measured using dcpix from multiple runs of an instrumented program. This makes it possible for dcpicalc to analyze counts from multiple runs of a program. dcpiwhatcg Produces a program-level summary breakdown of where time has been spent (percent of cycles spent in, e.g., memory delays, static stalls, branch mispredicts, and useful execution). dcpidiff Compares two sets of profiles for a procedure, highlighting basic blocks or source lines with the largest differences. dcpi2ps Formats a basic-block graph into Postscript. dcpictl Controls the operation of dcpid. This subsumes dcpiepoch, dcpiflush, and dcpiquit (which are still provided for backward compatibility). Adds functionality to tell the daemon about specific images loaded into processes when necessary (e.g., when an image is loaded via mmap). dcpiepoch Starts a new profiling epoch. All samples are associated with a time interval called an epoch. The analysis tools typically operate on a set of profiles from a single epoch. dcpiflush Flushes all unsaved samples from dcpid to profiles on disk. dcpiquit Terminates the dcpid daemon, flushing all unsaved samples to disk. dcpiscan Scans filesystem directories to find executables and associate executables with filesystem pathnames. dcpicat Prints the contents of one or more profile files in an ASCII format. dcpiflow Generates a basic-block graph for a procedure annotated with samples collected during profiling via dcpid. The functionality of this program has been subsumed by dcpicalc. dcpidis Disassembles a procedure and annotates the disassembly with samples collected during profiling via dcpid. This program is obsolete. Use dcpilist instead. The following DCPI commands are available on Digital Unix but not on Windows NT: dcpistats Compares multiple sets of raw sample counts and prints various statistics about them. Dcpistats is useful for comparing variations across multiple runs of the same program, or for comparing differences between slightly different versions of a program. Status: This is currently implemented as a shell script on Unix. dcpisource Augments a basic-block graph generated by dcpiflow with source code. Status: This is currently implemented as a shell script on Unix. dcpicc Compiles C programs to produce object code that helps dcpisource in identifying which source token each instruction corresponds to. Status: This is currently implemented as a shell script on Unix. dcpiversion Print the version string and creation date of the installed DIGITAL continuous profiling release. Status: This is currently implemented as a shell script on Unix. dcpiuninstall Uninstalls DCPI binaries and man pages, and restores the original version of /sbin/loader. Status: Use the Windows NT Control Panel's "Add/Remove Programs" icon to remove DCPI for Windows NT. dcpiloader A modified version of the standard dynamic loader that provides dcpid with information about where executables are loaded. Status: The "modified loader" is implemented in the device driver on Windows NT. dcpi2pix Converts DCPI profile data to pixie format. dcpikdiff Creates a new image based on both vmunix and kmem(7) that captures the true running kernel image after Digital Unix dynamically patches itself using self-modifying code. The following additional files are part of this kit: CPILIB.DLL Access library for CPIDRV driver CPIDRV.SYS Performance counter driver README.TXT This file ------------------------------------------------------------------------------ BUGS FIXED IN THIS RELEASE ------------------------------------------------------------------------------ * This is a new release. ------------------------------------------------------------------------------- CAVEATS ------------------------------------------------------------------------------- This kit is relatively new and still has some problems. The list below contains the things we know about right now: * The install procedure does not place the DCPI tools on the path. You can do this yourself by going to 'Properties' on 'My Computer', selecting "Environment", and adding the install directory to the path. * If you want to set DCPISVC to 'Automatic' to start it at system boot time, we advise you to create a separate boot configuration that does NOT include DCPISVC. NT will prompt you to select a boot configuration at startup time. * Profiles for images loaded after the daemon starts are likely to be stored as "unknown..." in the database. The image IDs are correct, however, so the tools should be able to find them in most cases. * Multiprocessor support has not been tested in a long, long time. * Occasionally, when stopping the DCPI Daemon, the service control manager will report that the daemon is not responding to the control function. DCPISVC does a flush before it shuts down, and the flush can often take long enough that the service control manager thinks the daemon has gone away. * The DCPI Control Panel is not very smart about what events can/should be multiplexed with others. In particular, it currently does not ensure that 'cycles' is selected on counter 0 if multiplexing is happening on the other counters. * Don't try to uninstall the software while it is running, do 'NET STOP DCPISVC' before running the uninstall procedure. * At this time, the DCPI tools can read only COFF symbols from executable files. When compiling your programs, be sure that you use the linker switches -DEBUG -DEBUGTYPE:BOTH or -DEBUG -DEBUGYPE:COFF. "Stripped" COFF symbols are supported, provided the DCPI tools can find the symbol files (.DBG) in the same directory as the executable, along _NT_SYMBOL_PATH, or along the regular search PATH.