atom - Builds an instrumented version of an application
program
atom appl_prog instrum_file [analysis_file] [options...]
atom appl_prog -tool tool_name [-env environ] [options...]
The first format of the atom command is used to create a
tool that instruments an application program. This format
requires the instrum_file parameter. The analysis_file
parameter is optional, because Atom can be used just to
examine a program statically, in which case no run-time
analysis routines are needed.
The second format of the atom command is more convenient
for regular use, because it locates the tool's instrumentation
and analysis files by a simple tool_name. This format
requires the -tool option and accepts the -env option.
It allows neither the instrum_file nor the analysis_file
parameter.
The following list describes those options used to invoke
Atom with a tool_name. Identifies the tool to be used by
naming the tool's description file (by default,
tool_name.desc). This text file names the instrumentation
and analysis files for the tool, as well as options that
the tool needs. By default, atom searches for the description
file in the /usr/lib/cmplrs/atom/tools and
/usr/lib/cmplrs/atom/examples directories. You can add
directories to the search path by supplying a colon-separated
list of additional directories to the ATOMTOOLPATH
environment variable. You can prevent Atom from searching
the default directories for the tool by including the keyword
NODEFAULT anywhere in the directory list specified by
the ATOMTOOLPATH environment variable. Identifies any
special environment (for example, threads) in which the
tool is to operate, by naming an alternative description
file (tool_name.environ.desc). Atom displays an error if
you specify an environment for which no description file
is found in Atom's search path.
Both formats of the atom command accept the following
options. Note that the listed default values apply only to
the first format. When the -tool option is specified,
required atom options and default atom, compiler, and
linker options may be defined by the specified tool's
description file. See the atom_description_file(5) reference
page for the syntax of the file. Indicates that
calls to analysis routines are not to be optimized. This
is the default. Optimizes the calls to analysis routines
by reducing the number of registers that need to be
restored. Specifying this switch causes Atom to generate
slightly larger, but faster code. Instruments all statically
loaded shared libraries in the shared executable.
Allows debugging of instrumentation routines. Atom puts
the control in dbx with a stop at the instrumentation routine.
See the Programmer's Guide for a discussion on how
to use dbx with Atom. Specifies a string for use when
reporting errors or warnings. By default, the string
"atom:" appears on all error or warning messages. Allows
debugging of instrumentation routines with the optional
ladebug debugger, if installed on your system. Atom puts
the control in ladebug with a stop at the instrumentation
routine. Use ladebug if the instrumentation routines contain
C++ code. See the Ladebug Debugger Manual for more
information. Specifies that objname is a dynamic shared
library (that is, one loaded by a call to dlopen(3)). You
must specify each of the application's dynamic shared
libraries in either a -dynobj option or an -incobj option.
Those libraries specified to the -dynobj option are not
instrumented; those specified to the -incobj option are.
Excludes the named shared library from instrumentation.
You can use the -excobj option more than once to specify
several shared libraries. Note that when -pthread is specified
(typically in a tool's description file for the
"threads" environment), Atom automatically instruments
parts of libpthread.so even if it is specified in the
-excobj option. Specifies that fork support is required.
This option should be used to avoid deadlocks in multithreaded
applications. When this option is used, fork handling
routines declared by a call to pthread_atfork in
analysis code or libraries are also activated, to enable
the tool to be thread-safe and to handle forks as desired.
See the prof example tool. Produces the instrumented program
with debugging information. This enables debugging of
analysis routines. The default -A0 option (not -A1) is
recommended when -ga (or -g) is used. Produces the
instrumented program with debugging information. This
enables debugging of analysis and application routines.
The prefix "_APP_" is attached to all variable and procedure
names in the application (this option does not work
with C++ programs). The default -A0 option (not -A1) is
recommended when -gap is used. Produces the instrumented
program with debugging information. This enables debugging
of application routines. Produces the instrumented program
with debugging information. This enables debugging of
analysis and application routines. The prefix "_ANA_" is
attached to all variable and procedure names in the analysis
object (this option does not work with C++ programs).
The default -A0 option (not -A1) is recommended when -gpa
is used. Changes the base of the analysis heap. This
option has three forms: Sets the base to the given hex
address. Sets the base to a default 31-bit address that
is safe for applications that expect analysis addresses to
fit in 31 bits. Sets the base to the first page after the
end of the application's bss segment. This puts the heap
base in about the same place as the application's heap.
You should only specify this for tools that intercept
every heap allocation in the application program.
Normally, Atom's default location for the analysis
heap is sufficient, so you don't need to use the
-heapbase option. However, if the default location
conflicts with an address range used by the application
program, you may have to choose a new location
for the analysis heap. Allows reuse of a previously
instrumented shared library. With -ii
(incremental instrumentation), the first time that
a shared library is instrumented, the instrumentation
points will be added to the shared library and
additional information that allows for subsequent
reuse will be added. If previously instrumented
shared libraries are found, those libraries will be
updated and reused. For reuse to occur, the options
that are specified must be the same for both Atom
and the tool (if specified). Instruments the named
shared library. You can use the -incobj option
more than once to specify several shared libraries.
Note that if the tool calls ThreadExcludeObj(5) for
a multithreaded program, this function will advise
the tool not to instrument certain threads-related
system libraries even if they are selected. This
ensures that the analysis is thread-safe. Indicates
that the temporary files that Atom creates
should be placed in the current working directory,
and not deleted when instrumentation is complete.
Changes the library directory search order for
shared object libraries so that atom searches for
them in dir before searching the default library
directories. You can specify multiple -Ldir
switches to specify several directory names.
Changes the library directory search order for
shared object libraries so that atom never looks
for them in the default library directories. Use
this option when the default library directories
should not be searched and only the directories
specified by -Ldir are to be searched. Updates
shared libraries with instrumented shared library
information. By default, this information is only
added to the instrumented application.Using this
option is not generally recommended. Includes
LD_LIBRARY_PATH in the search path for shared
libraries. Paths specified with -L are searched
first, then RPATH, then LD_LIBRARY_PATH, and then
the default directories. Produces a list of the
starting addresses of the sections in the instrumented
executable. Indicates that the tool will be
instrumenting libc to clear the uniq register, so
Atom should not do it. Using this option is not
generally recommended. Indicates that the tool
will be instrumenting libc to execute the analysis
fini routines, so Atom should not do it. Using this
option is not generally recommended. Names the
executable output file filename. By default, when
the first format of the atom command is used, the
file is called progname.atom. When the second format
of the atom command is used, the file is called
progname.toolname, or progname.toolname.environ if
the -env environ option is used. Specifies that
thread-safe support is required. This option should
be used when instrumenting threaded applications.
Specifies an existing directory to which atom
writes the instrumented shared libraries. Using
this option allows you to keep all of an application's
instrumented shared libraries in a single
place. Specifies a filename suffix that is
appended to the name of each object when Atom
writes the instrumented version. For instance,
specifying -suffix third would cause a shared
library such as libc.so to be written as
libc.so.third and a main executable file such as
test1 to be written as test1.third. If you do not
specify the -tool option, the suffix defaults to
the name of the tool. Passes arguments to the Atom
tool's instrumentation routines. Use whitespace
characters to separate arguments from their parameters
(if any) and from other arguments.
If you need to represent spaces within a -toolargs
argument, use matching single-quotes or matching
double-quotes, making sure that you avoid having
the shell interpret those characters as shell-special
characters. For example:
-toolargs="-exc 'strstreambase::strstreambase(char*,
int, char*)'"
-toolargs='-exc "operator -" -exc "ostream::operator
<<" \
-exc main -exc "operator new(unsigned
long)"' Displays each step Atom takes to create the
instrumented program. Displays Atom's version number.
Controls display of warning messages. The
value of n can be one of the following values: Display
all warning messages, including those that are
normally suppressed. Suppress warning messages
that can be safely ignored. This is the default.
Suppress warning messages emitted when processing
analysis routines. Suppresses warning messages
about shared library processing errors. Atom
ignores shared libraries that cannot be processed.
Passes the specified options to the analysis file's
link phase. Passes the specified options to the
instrumentation file's link phase. Passes the
specified options to the analysis file's compilation
phase. Passes the specified options to the
instrumentation file's compilation phase.
File name of a fully linked shared or nonshared executable.
For multithreaded programs, run ld(1) and atom(1)
on the same version of Tru64 UNIX. Multithreaded programs
linked on DIGITAL UNIX V3.2 are not supported, because the
thread support libraries are not compatible with atom.
Programs that are stripped or are optimized by spike or cc
-om are not supported. Name of a C source file or an
object module that contains the Atom tool's instrumentation
procedures. By convention, most instrumentation
files have the suffix inst.c or inst.o, respectively. If
the instrumentation procedures are in more than one file,
the of each file may be linked together into one file
using the ld command with a -r option.
If you pass an object module for this parameter,
consider compiling the module with either the -g1
or -g options. If there are errors in your instrumentation
procedures, Atom can issue more complete
diagnostic messages when the instrumentation procedures
are thus compiled. Name of a C source file
or an object module that contains the Atom tool's
analysis procedures. By convention, most analysis
files have the suffix anal.c or anal.o, respectively.
Analysis routines may perform better if
they are compiled as a single compilation unit. If
the analysis routines are in more than one file,
the of each file may be linked together into one
file using the ld command with a -r option.
Atom is a programmable instrumentation toolkit. You program
it by writing a tool with a routine called Instrument
or InstrumentAll that calls Atom's API, as described in
the related reference pages. The API helps this routine to
discover the shared libraries, procedures, basic blocks,
and instructions that make up an application. Then the API
helps the routine insert calls to the tool's own run-time
analysis routines, so that they will be invoked before or
after the application (or any of its libraries, procedures,
blocks, or instructions) are executed. The application
code's behavior is unchanged in the instrumented program,
but the tools's analysis routines execute too, producing
tool-specific analysis data, such as an event trace
or a profile.
Temporary instrumentation files are created in /tmp. Set
the TMPDIR environment variable to a different directory
to create the files elsewhere, for example in a disk partition
with more space.
Atom does not work on programs built with the -pg or -p
option.
Instrumented code can be substantially larger than the
original code. In rare cases, conditional branches that
fit in the 21-bit branch displacement field may not do so
in the instrumented version of the code, thus generating
an error.
The following is a list of library routines that can and
cannot be called by analysis routines: Standard C Library
(libc.a) routines (including system calls) can be called
except for unwind(3) routines and other exception-handling
routines.Also, the standard I/O routines have certain differences
in behavior as described later in this section.
The pthread_atfork routine can be called only if the -fork
was used during program instrumentation. Math Library
(libm.a) routines can be called. Other routines related
to multi-threading or exception-handling should not be
called (for example, pthread(3), exc_*, and libmach routines).
Other routines that assume a particular environment
(for example, X and Motif) may not be useful or correct
in an Atom analysis environment.
The standard I/O library provided to analysis routines
does not automatically flush and close streams when the
instrumented program terminates, so the analysis code must
flush or close them explicitly, when all output has been
completed.
Also the stdout and stderr streams that are provided to
analysis routines will be closed when the application
calls exit(), so analysis code may need to duplicate one
or both of these streams if they need to be used after
application exit (for example, in a ProgramAfter or
ObjAfter analysis routine -- see AddCallProto(5)).
For output to stderr (or a duplicate of stderr) to appear
immediately, analysis code should call setbuf(stream,NULL)
to make the stream unbuffered or call fflush after each
set of fprintf calls. Similarly, analysis routines using
C++ streams can call cerr.flush().
Thread Local Storage (TLS) is not supported in analysis
routines.
In the degenerate case of using Thread Independent Service
(TIS) routines or Thread Local Storage (TLS) in a nonthreaded
or single-threaded call-shared program, libc.so
must be instrumented. This can be accomplished using -all
or -incobj libc.so on the atom command line. In nonshared
programs, libc.a is always instrumented.
INSTRUMENTING SHARED LIBRARIES [Toc] [Back] If you specify either the -all or -incobj switch, Atom
instruments an application and the application's shared
libraries. The instrumented shared libraries are written
to the current directory with the suffix. For example,
libc.so is written as libc.so.atom.
By default, Atom searches for shared libraries in the same
locations as the linker: /usr/shlib /usr/ccs/lib
/usr/lib/cmplrs/cc /usr/lib /usr/local/lib /var/shlib
If the shared library is not found in any of the above
locations, then Atom will search the current working
directory.
If you specify the -Ldir option, Atom searches the given
directory before searching the default locations. You can
specify multiple -Ldir options. You can also supply the
-L option without a directory name. This causes Atom to
avoid searching the default directories. Only those
directories specified by -Ldir options are searched.
The loader uses only the instrumented shared libraries for
those applications that have been instrumented. As long
you choose a unique suffix name (using the -suffix option)
for the instrumented files, you can even run an application
instrumented with two different Atom tools. The
loader picks up the correctly instrumented shared library
for each version of the instrumented application.
The following example tools can be named with the -tool
option. These tools are intended to show how new tools can
be written. They may not work well on all applications:
-----------------------------------------------------------
Tool Description
-----------------------------------------------------------
branch Instruments all conditional branches to determine
how many are predicted correctly.
cache Determines cache miss rate. Simulates execution
of the application in 8KB direct-mapped cache.
dtb Determines the number of dtb (data translation
buffer) misses. Simulates execution of the
application in 8KB pages and with a fully associative
translation buffer.
dyninst Provides fundamental dynamic counts of instructions,
loads, stores, blocks, and procedures.
inline Identifies potential candidates for inlining.
iprof Prints the number of times each procedure is
called as well as the number (dynamic count) of
instructions executed by each procedure.
malloc Records each call to the malloc function and
prints a summary of the application's allocated
memory.
prof Prints the number (dynamic count) of instructions
executed by each procedure, in a threadsafe
manner.
ptrace Prints the name of each procedure as it is
called.
replace Replaces an application procedure, and calls it
from the analysis routine.
trace Generates an address trace, logs the effective
address of every load and store operation, and
logs the address of the start of every basic
block as it is executed.
xlate Demonstrates how to use XLATEs to call an application
procedure from an analysis routine.
-----------------------------------------------------------
This example invokes the iprof example tool to instrument
program, producing the executable output file program.iprof.
atom -tool iprof program This example instruments
program using the instrumentation file my.inst.c and
analysis file my.anal.c, producing the executable output
file program.atom. atom program my.inst.c my.anal.c
Functions: atom_application_instrumentation(5),
atom_application_navigation(5), atom_application_query(5),
atom_application_symbols(5), atom_description_file(5),
atom_instrumentation_routines(5), atom_object_management(5), AnalHeapBase(5), Thread(5), Xlate(5)
Programmer's Guide
atom(1)
[ Back ] |
