Release Notes for NT-Atom 1.53 Developed by Advanced Development Group Advanced and Emerging Technologies April 5, 1999 NT-Atom is a flexible tool for instrumenting and analyzing programs. It works by inserting instrumentation points into an executable image at procedure, basic block, or instruction boundaries. Atom can be used to design useful performance and debugging tools such as basic block counters, cache simulators, and profilers. NT-Atom is based on the Unix version of Atom. In this beta release, we support the ATOM instrumentation routines under Windows NT 4.0 only. In order to develop custom instrumentation and analysis tools, Visual C++ 5.0 or higher must be installed, although it is not required if only the standard tools are used. Installation notes NT-Atom can be installed by first copying the zipped ntatom kit to a temporary location and then unzipping the files. The installation can be initiated by running the setup.exe file. If the NT-Atom kit is not zipped, the installation can be started directly by running setup.exe. Setup.exe will prompt the user for the location in which to install NT-Atom. The default behavior is to create the following directory structure under drive:\NTAtom\: BIN ntatom executables and dependent dlls DOCS ntatom helpfile Examples Contains example tools and programs Include Contains include files for developing custom tools. Progs Example programs to be instrumented Src Source for example NT Atom instrumentation and analysis program files Lib Ntatom libraries Packages Stdtools Directory containing the standard examples. Readme this file The installation of NT-Atom sets the following environment variables: ATOMDIR directory of NT Atom installation. ATOMTOOLPATH directory of NT Atom packages. The installation of NT-Atom can be moved to a different root directory, if desired. If so, the above environment variables will have to be changed to reflect the new directory installation. Example: NT-Atom installation is moved to r:\ntatom. set ATOMDIR=r:\ntatom set ATOMTOOLPATH=r:\ntatom\packages The installation of NT-Atom also sets the PATH system variable. For example, if NT-Atom is installed in r:\ntatom, then path can be set as follows: set PATH=%PATH%;r:\ntatom\bin;r:\ntatom\packages\stdtools NT-Atom can be used in either a command line interface or in a graphical user interface mode. To invoke the graphical user interface form of NT-Atom, type the following from a console window: ntatom_gui Once the GUI has been launched, there are various menu options that will allow for the selection of an application for instrumentation and the specification of files to be used in the instrumentation process. Please see the help file on the NT-ATOM GUI for more details on how to use NT-Atom's graphical user interface. NT-Atom can also be used in a command line interface mode. In this mode, NT-Atom has two forms in which it can be invoked: ntatom app.exe -tool toolname [-env environ] [options...] ntatom app.exe instrum_file [anal_file] [options...] The first form uses the NT-Atom standard tools and the second form allows the development of custom user instrumentation and analysis programs. The standard tools are described below in the section on NT-Atom standard tools. Examples of instrumentation and analysis files can be found in the Examples\src directory. The include directory contains the file "atom.inst.h" that needs to be included with any custom instrumentation file in order for NT-Atom to function properly. See the ntatom.hlp document for further usage information and options for the command line interface. Note that NT-Atom creates and remove temporary files. These new files are created in the directory containing the executable to be instrumented. NT-Atom Standard Tools This release of NT Atom contains the following standard tools. They are accessible via the command-line flag -tool . The following tools are provided with this distribution of NT Atom: Branch Cache Dtb Dyninst Pixie Trace Hiprof Iprof Prof Static Ptrace Malloc Dcache Third The output files are of the form .toolname where is the name of the executable to be instrumented less the ".exe" extension and toolname is the name of the tool (e.g. ptrace) . If the executable name is not of this form or the program is unable to open the file with that name, the output file will be named .out. Notes: Please be aware that Visual C++ performs some default code optimizations. This may lead to strange results when analyzing the data for instrumented code. However, NT-Atom does not track any of these changes. Therefore, to ensure the proper analysis of compiled code, it is recommended that compilation be performed with the "/Od" flag, disabling optimizations for debugging purposes. The output file will usually be produced in the same directory as the instrumented executable. However, in rare cases, output files will be directed to application specific directories. Branch This tool simulates the branch prediction unit. It logs the program counter (PC), the number of references, and the prediction success rate for each reference. It also prints a summary of the data collected. Output file: .branch Cache This tool simulates the operation of a 8Kb direct mapped cache on the instrumented executable. It records the number of cache references and misses as well as calculating the miss rate. Output file: .cache Dtb Dtb simulates the operation of a fully associative data translation buffer (dtb) on the executable, assuming 8Kb pages. It logs the number of dtb hits, misses, and references and calculates the dtb miss rate. Output file: .dtb Dyninst Dyninst provides a dynamic (runtime) count of loads, stores, blocks, and procedures. output file: .dyninst Hiprof Hiprof tool is an NT-Atom based program profiling tool that produces both flat and hierarchical profiles. The flat profile shows the execution time spent in any given procedure. The hierarchical profile shows the time spent in a given procedure and all its descendents. See the section on Hiprof for further information and tool arguments. Output file: .hiprof Prof Prof logs a dynamic count of the number of instructions executed per procedure. It also provides the percentage of time (in instructions) spent in each procedure. output file: .prof Iprof Iprof is similar to prof (see above) but also displays the number of instructions executed (dynamic count) for each procedure. output file: .iprof Static Static collects static information about the executable. It provides the following information for each procedure found in the executable: the name of the procedure the number of basic blocks in each procedure the length of the procedure based on summing the length of each block in the procedure the length of the procedure based on the information provided by GetProcInfo(procedurePtr,ProcNumberInsts). Output file: .static Pixie Pixie records the number of times a basic block is visited, referenced by the address of the first instruction in the block. Output file: .pixie Trace Trace logs instruction and data references. It also logs the procedure name upon entrance. Loads and stores have their data references (Dref) logged by address and the PC of the first instruction of a basic block (Iref). (the generated output files can be quite large) Output file: .trace Ptrace Ptrace records procedure invocations. Upon entering a procedure, it logs it. If the procedure name is unknown, it generate a procedure name of the form: proc_at_
, where
is the address of the procedure in the program text segment. Output file: .ptrace Dcache This tool simulates the operation of an 8Kb and 16KB direct-mapped data cache with a 32 byte line size. The user can optionally supply values for a third cache size and line size. Output file: .cache Malloc This tool records each call to malloc and free. The program must have debug symbols included. Output file: .malloc Third This tool is a heap usage and leak profiler, and memory-access error checker for C and C++ programs. See the help section on using Third for more information. Output file: .third NT-ATOM APIs The following functions are supported in this version of NT- Atom: Image level navigation routines: GetFirstObj, GetLastObj, GetNextObj, GetPrevObj, and GetProcObj Procedure level navigation routines GetFirstObjProc, GetLastObjProc, GetNextProc, GetPrevProc, and GetBlockProc. Block level navigation routines GetFirstBlock, GetLastBlock, GetNextBlock, GetPrevBlock, and GetInstBlock. Instruction level navigation routines GetFirstInst, GetLastInst, GetNextInst, GetPrevInst, and GetInstBranchTarget. Program level query routines GetProgInfo and GetAnalName. Image level query routines GetObjInfo, GetObjName, GetObjOutName, GetObjInstArray, and GetObjInstCount. Procedure level query routines ProcName, ProcPC, GetProcInfo, and ProcFileName. Block level query routines GetBlockInfo, BlockPC, and IsBranchTarget. Instruction level query routines GetInstClass, IsInstType, GetInstInfo, InstPC, InstLineNo, GetInstBinary, GetInstRegEnum, and GetInstRegUsage. Miscellaneous routines BuildObj, WriteObj, IsObjBuilt, IsMainObj, ReleaseObj, InstrumentAll, InstrumentInit, InstrumentFini and Instrument. ResolveTargetProc, ResolveNamedProc, ReResolveProc, BuildProcFlowGraph, and ReleaseProcFlowGraph Prototype definition routines AddCallProto, AddCallReplaceProto Insert analysis routine calls AddCallProgram, AddCallObj, AddCallProc, AddCallBlock, AddCallInst, ReplaceProcedure Address translation routines CreateXlate, AddXlateAddress Examples C:>ntatom cal.exe -tool pixie NT-ATOM: version 1.0 C:>cal.exe.atm May 1997 S M Tu W Th F S 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 In this example, NT-Atom instruments the file cal.exe with the standard tool pixie. The default instrumentation file, cal-atm.exe is produced and run. As a side effect of the execution of cal-atm.exe, a file called cal.pixie is produced. This file contains addresses of each basic block in the program and the number of times it was executed. The output has a form similar to the following: B 40201c 1 B 402034 1 B 402084 1 B 402140 1 B 402148 1 ... B 40222c 1 B 402270 6 B 402288 42 B 402294 42 ... etc. The installation provides two example programs to be executed. These files are located in the installation directory Examples\progs\. Examples of instrumentation and analysis programs can also be found in the installation directory examples\src\. The following are examples of the use of the example programs with the example instrumentation and analysis programs and the standard tools. In this example, NT-Atom instruments the file dotprod.exe with instrumentation and analysis program files ptrace.inst.c and ptrace.anal.c found in the Examples\atomprogs directory. Because these are c files, the Visual C++ compiler must be installed and the C compiler (cl.exe) and linker (link.exe) capable of being invoked from the command line. C:\>ntatom dotprod.exe ..\atomprogs\ptrace.inst.c ..\atomprogs\ptrace.anal.c NT-ATOM: version 1.0 C:>dotprod-atm.exe The dotproduct is 20.000000 C:>more < dotprod.ptc mainCRTStartup _heap_init __sbh_new_region memset _ioinit _malloc_dbg _nh_malloc_dbg _heap_alloc_dbg _CrtDefaultAllocHook _heap_alloc_base __sbh_alloc_block __sbh_alloc_block_from_page ... etc. NT-Atom firsts compiles the ptrace.inst.c file and links it with any necessary NT-Atom libraries to form an instrumentation Dll (inst.dll). The progress of the compile and link are reported to stdout, as are any errors that might occur in a user's instrumentation program. This Dll will be loaded into memory and used to instrument the program dotprod.exe. NT-Atom next compiles the ptrace.anal.c file and links it as a Dll (anal.dll). This Dll is loaded into memory when the dotprod- atm.exe command is invoked. The side effect of executing dotprod-atm.exe is to create a file called dotprod.ptrace, which contains a trace of all of the procedures called when a program is run. Changes from last release The following changes have been made since the last release of NT-Atom: - NT-Atom now uses SPIKE version 1.4. - Beta version of Third Degree included in the standard tools. In addition, the following bugs have been fixed: - Fixed a bug with the Xlate function that did not allow its use with AddCallObj. Removed the size limitations on Xlate tables. - Fixed a bug with the passing of floating point register values. This now requires the use of FREGV in the AddCallProto. - The -suffix extension now produces the same suffixes with both the GUI and the command line interface. - Spaces in the pathname of an executable or other filenames used by NT-Atom are now permissible. - Fixed a problem with ReleaseObj that caused subsequent BuildObjs to fail. - Fixed a bug with the ObjModifyHint option of GetObjInfo. This now works properly. - Fixed a problem with the GetInstRegUsage in connection with the FCMOVxx and the CMOVxx instructions. This now works properly. Known Limitations Limited to Windows NT 4.0. Visual C++ 5.0 or higher must be installed to use custom instrumentation and analysis programs. In order to generate symbols, you should compile with /Zi and link with /debugtype:cv. Other types of debug information such as COFF will provide symbol information. Line numbers and source filename information is, however, only provided with codeview (via the .PDB file) at this time. Thread-safe versions of the standard tools are not available with this release. The standard tools assume only a single thread of execution. Instructions in the prologue of a procedure are not currently instrumented. Therefore, an instrumentation program that counts the number of loads and stores in a program will not include the prologue loads and stores in this instruction count. It will be possible to instrument prologue instructions in a future version of NT-Atom. Debug symbols are currently stripped from the executable image if they are present. This will change in a future release of NT-Atom. The GetInstBinary instruction is not implemented. Use the GetInstInfo(Inst, InstBinary) instead. Acknowledgements The Atom technology for Unix was developed at WRL by Alan Eustace and Amitabh Srivastava. We re-used a significant part of the Unix Atom code in the development of NT-Atom. NT-Atom is built on top of SPIKE, developed at Hudson by Geoff Lowney, Robert Cohn, David Goodwin and others. In addition to supplying us with code, we are greatly indebted to them for all of their help and recommendations in the design of NT-Atom. Sharon Smith developed the NT-Atom instrumentation engine. Eric Betts developed the graphical user interface for NT-Atom version B.3. Jack Tihon ported over the standard UNIX tools to Windows NT. Lisa Eklund developed an early prototype for the graphical user interface. David Hunter has developed several of the tools, tested much of the ntatom core and remains our fearless leader. Further Documentation ntatom.hlp - describes in detail the usage for the command line interface of NT-Atom. NT-Atom Tool Development Guide - an overview of how to develop custom tools in NT-Atom. Bug Reports Send any bug sightings, comments or suggestions to ntatom-bugs@pa.dec.com.