Release Notes Program Analysis Tools Version 2.10 Atom Release V3.26 September 2002 *********************************************************************** * * * Copyright M-) 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 " 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 - 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 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.