		                 Release Notes 
                     Program Analysis Tools Version 2.10
			     Atom Release V3.26
			        September 2002

  ***********************************************************************
  *                                                                     *
  *	Copyright  2002 Compaq Computer Corporation			*
  *									*
  *	COMPAQ Registered in U.S. Patent and Trademark Office.		*
  *									*
  *	Confidential computer software. Valid license from Compaq 	*
  *	required for possession, use or copying. Consistent with 	*
  *	FAR 12.211 and 12.212, Commercial Computer Software, Computer 	*
  *	Software Documentation, and Technical Data for Commercial 	*
  *	Items are licensed to the U.S. Government under vendor's 	*
  *	standard commercial license.					*
  *                                                                     *
  ***********************************************************************


1. Introduction
---------------

The Program Analysis Tools V2.10 field test kit installs new versions of
the Tru64 UNIX command line program analysis tools, such that they can 
be invoked with no change to the user's command line or environment:
 - Atom V3.26 (September 30, 2002), in two subsets:
    - "Atom Run-time (Program Analysis Tools)" is a mandatory subset
      that provides the files needed to use an Atom-based tool.
    - "Atom Development (Program Analysis Tools)" is an optional subset
      that provides the headers, man-pages, and examples needed to
      develop an Atom-based tool.
 - Integrated profiling tools and the gprof and prof commands that they 
   use, in another subset:
    - "Hiprof, Pixie, Third Degree (Program Analysis Tools)" 
      is an optional subset that provides three application profiling and
      testing commands, which were first introduced with Tru64 UNIX V5.0.

2. Changes since Program Analysis Tools V2.0
--------------------------------------------

This field test kit is a minor update to the Program Analysis Tools, providing
further improvements in robustness along with the following enhancements
relative to the Program Analysis Tools V2.0 kit.


2.1 Support for all Tru64 UNIX versions

Support is now provided for all versions of Tru64 UNIX that HP plans to
support for at least 6 months: V4.0F, V4.0G, V5.0A, V5.1, V5.1A and
V5.1B once it becomes available.

The libst.a library and headers used by Atom also support all the object
file formats found on the supported versions of the operating system.


2.2 Support for Alpha EV7 processors

Support is now provided for object files that exploit new features of the 
Alpha EV7 architecture.


2.3 Support for Section Alignment

Object files compiled on Tru64 UNIX V5.1B may have section alignment 
attributes that are not supported by the Program Analysis Tools V2.0 or
V2.05 kits.  Atom now supports objects with section alignment attributes.


2.4 Improved handling of stripped shared libraries

In previous versions, ATOM ignored stripped shared libraries and their
shared library dependencies. Stripped shared libraries do not 
contain all of the information required by ATOM to do its work. 
Atom now reads the dependencies of stripped shared libraries, allowing
them to be instrumented unless they are also stripped.


3. Changes since Program Analysis Tools V1.1
--------------------------------------------
 
This field test kit is a major update to the Program Analysis Tools, providing
further improvements in robustness along with the following enhancements 
relative to the Program Analysis Tools V1.1 kit.


3.1 Updated headers and man-pages

Updated header files and man-pages are now provided, to support the use of 
the latest features of the Atom and libst APIs - beyond those described by 
the default headers and man-pages installed with the operating system.

The new files do not replace the originals, but when the atom(1) command
from this kit compiles a tool's source files it uses the headers from
this kit, and other commands (such as cc(1) and man(1)) can use the new
files too. See the Documentation section below.

Atom's updated run-time components remain compatible with those of the 
version provided with the operating system, so they can be used with 
tools' sources or binaries implemented with either the original or
updated versions of the header files.


3.2 New example tools

The complete set of existing Atom examples is included, along with new ones
to illustrate new APIs, as described in the atom(1) man-page. The examples
are placed in the /usr/lib/cmplrs/atom.dtk/Atom/examples directory.


3.3 New APIs to instrument individual entry points

New GetFirstEntry, GetLastEntry, GetNextEntry, GetPrevEntry, and GetEntryBlock
APIs let tools distinguish alternate entry points of a procedure, and the
related AddCallEntry, GetEntryInfo, GetEntryProc, EntryName, and EntryPC APIs 
let tools instrument entry points individually. 

Also, the new AddXlateEntry API lets analysis code find the loaded address 
of an entry point, even one that has been instrumented or replaced, such 
that it can be called. The existing AddXlateAddress API continues to
provide the address of a given instruction, but making a procedure call
to such an address is not supported.


3.4 New APIs to replace procedures

A new ReplaceEntry and ReplaceProto API obsoletes ReplaceProcedure
(retained for compatibility with previous releases). It supports
intercepting calls to specific procedure entry points such that 
input arguments, implementation, and return values can be modified.  
It also allows additional arguments to be passed to the intercepting
analysis code, as for other analysis routines.  The "replace" example
demonstrates this and other APIs that support entry points.


3.5 New APIs to resolve symbol names and jump targets

A set of new Find* and GetTarget* APIs are described in the new
atom_application_symbols(5) man-page. They obsolete the APIs described 
in the atom_application_resolvers(5) man-page, and they allow resolution 
of symbols and jump target addresses to individual entry points, which 
can be instrumented and replaced more precisely than procedures.


3.6 Automatic setting of rpath

If an instrumented executable depends on shared libraries to resolve symbols,
Atom now sets the executable's rpath to indicate the directory that contains
any instrumented versions of those shared libraries. This eliminates the
need for the user to define the LD_LIBRARY_PATH environment variable.

Also, Atom's new -loadpath option tells Atom to look in the LD_LIBRARY_PATH
directories when instrumenting the shared libraries used by an application.


3.7 New tool-development options

Atom now offers new options to help tool writers:
 - The -map option prints a map of the address of each section in the
   instrumented executable.
 - The -keep option retains temporary files (such as the fully linked
   instrumentation tool) in the working directory, so that they can be
   analyzed beyond the debugging supported by -debug. The -v option shows
   the subordinate commands that generate or execute each temporary file.
 - The -w3 option suppresses warnings about shared libraries that are
   ignored (since they can not be instrumented). Passing ProgNumErrantShlibs
   to GetProgInfo now yields the number of such libraries, and the new APIs
   GetErrantShlibName and GetErrantShlibErr return their name and error.
 - Atom's new "-errstring <string>" will print the given string instead
   of "atom" on any error reporting from Atom.  This allows tool writers
   to hide the fact that their tool uses Atom's services.


3.8 Improved pthread support

The -pthread option offered by Atom, Hiprof, Pixie, and Third Degree
now supports the pthread(3) package more reliably, particularly when 
combined with the -fork option for handling fork(2), nfork(2), and 
vfork(2). (On V4.0 systems, Third Degree must still use the old support.)

Atom's -fork option obsoletes the existing ThreadForkCall API.  New 
ThreadCreationProc and ThreadTerminationProc APIs build on and obsolete
the existing ThreadExitCall API.  The "prof" example has been updated 
to demonstrate pthread support with the new APIs.


3.9 Faster repeat instrumentation

The Hiprof, Pixie, and Third Degree tools now reuse previously instrumented
shared libraries if they were instrumented with the same options and input
files as those required now. This can dramatically reduce the time needed
to reinstrument a program again after editing or recompiling, for example.


3.10 Improved labelling of prof profiles

The default profile produced by prof is now more realistically labelled,
as instruction counts instead of cycles, and warnings are printed to
indicate the limited accuracy of the cycles counts reported when the
user specifies the -truecycles, which otherwise keeps the old stdout 
format.


3.11 New profile directed optimization

Pixie's new "-stats dstride" option can be used to generate a new kind
of profile that can drive new data prefetch optimizations in spike(1).


4. Documentation
----------------

This Program Analysis Tools kit includes new and updated man-pages
and header files.

The updated man-pages for commands will be displayed by a standard 
man(1) command, instead of the pages installed by the operating system
kit. The originals will become available again if this kit is deleted.
Man-pages are provided in this way for the atom(1), gprof(1), 
hiprof(1), pixie(1), prof(1), prof_intro(1), and third(1) commands.

The man-pages that match the APIs for either the operating system's
version or the Program Analysis Tools version of the Atom and libst
header files can be displayed:
 - Original header files of the operating system, in /usr/include:
	man <function name>
 - Updated header files installed by the "Atom Development (Program 
   Analysis Tools)" subset, in /usr/lib/cmplrs/atom.dtk/Atom/include:
	man -M /usr/lib/cmplrs/atom.dtk/Atom/man <function name>

Atom uses the new headers automatically, if it compiles a tool from source.
To compile a tool separately, add a suitable -I option to the compile
command: for example, "cc -I/usr/lib/cmplrs/atom.dtk/Atom/include ..."

The Programmer's Guide is not updated for this field test release.
A Programmer's Guide is provided as HTML files that can be viewed 
with an Internet Web Browser such as the netscape(1) browser 
provided with the operating system. The guide is installable as 
a separate kit included with the Developers' Toolkit Supplement.  
The URL is file:/usr/share/doclib/dtk/guide/index.html - type this on 
the "Location:" line in the netscape(1) window or on its command line. 


5. Using the Old Versions of the Program Analysis Tools
-------------------------------------------------------

The original atom, gprof, pixie, and prof commands provided by the 
operating system can be accessed by specifying the "-nodtk" option 
on their command lines. The new hiprof and third commands had no 
equivalent in Tru64 UNIX V4.0* operating system releases, so on
such systems they do not support the "-nodtk" option.

An "atom -tool ..." command will use the new version of the named
tool by default. An "atom -nodtk -tool ..." command will use the
old version of the tool.




