
	   	  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 <toolname>.  
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 <filename>.toolname where 
<filename> 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 <toolname>.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: <filename>.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: <filename>.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: <filename>.dtb 

Dyninst
Dyninst provides a dynamic (runtime) count of loads, 
stores, blocks, and procedures.
output file: <filename>.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: <filename>.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: <filename>.prof

Iprof
Iprof is similar to prof (see above) but also displays the 
number of instructions executed (dynamic count) for each 
procedure.
output file: <filename>.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: <filename>.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: <filename>.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: <filename>.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_<address>, where <address> is the address of the 
procedure in the program text segment.
Output file: <filename>.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: <filename>.cache

Malloc
This tool records each call to malloc and free.  The 
program must have debug symbols included.
Output file: <filename>.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: <filename>.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.


