atom(1)atom(1)NAMEatom - Builds an instrumented version of an application program
SYNOPSISatom appl_prog instrum_file [analysis_file] [options...]
atom appl_prog -tool tool_name [-env environ] [options...]
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 anal‐
ysis 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 instrumenta‐
tion routines. Atom puts the control in dbx with a stop at the instru‐
mentation 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 Lade‐
bug 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 instrumen‐
tation. You can use the -excobj option more than once to specify sev‐
eral shared libraries. Note that when -pthread is specified (typically
in a tool's description file for the “threads” environment), Atom auto‐
matically 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 debug‐
ging 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 applica‐
tion (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 debug‐
ging 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++ pro‐
grams). 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 analy‐
sis 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 suf‐
ficient, so you don't need to use the -heapbase option. How‐
ever, 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 instrumenta‐
tion), 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 spec‐
ify 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 direc‐
tory, 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 directo‐
ries. 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 instru‐
mented 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 exe‐
cutable 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)"' Dis‐
plays 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 emit‐
ted when processing analysis routines. Suppresses warning mes‐
sages 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 com‐
pilation phase.
OPERANDS
File name of a fully linked shared or nonshared executable. For multi‐
threaded programs, run ld(1) and atom(1) on the same version of Tru64
UNIX. Multithreaded programs linked on DIGITAL UNIX V3.2 are not sup‐
ported, 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, respec‐
tively. If the instrumentation procedures are in more than one file,
the of each file may be linked together into one file using the ld com‐
mand with a -r option.
If you pass an object module for this parameter, consider com‐
piling 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 pro‐
cedures 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.
DESCRIPTION
Atom is a programmable instrumentation toolkit. You program it by writ‐
ing 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 rou‐
tines, so that they will be invoked before or after the application (or
any of its libraries, procedures, blocks, or instructions) are exe‐
cuted. 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.
NOTES
Temporary instrumentation files are created in /tmp. Set the TMPDIR
environment variable to a different directory to create the files else‐
where, for example in a disk partition with more space.
RESTRICTIONS
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 dis‐
placement 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 sec‐
tion. 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 lib‐
mach 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 auto‐
matically flush and close streams when the instrumented program termi‐
nates, 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 rou‐
tines 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) rou‐
tines or Thread Local Storage (TLS) in a non-threaded 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
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 appli‐
cations that have been instrumented. As long you choose a unique suf‐
fix 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.
EXAMPLE TOOLS
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 deter‐
mine 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 asso‐
ciative translation buffer.
dyninst Provides fundamental dynamic counts of instruc‐
tions, 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 instruc‐
tions executed by each procedure, in a thread-
safe 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 appli‐
cation procedure from an analysis routine.
───────────────────────────────────────────────────────────
EXAMPLES
This example invokes the iprof example tool to instrument program, pro‐
ducing the executable output file program.iprof. atom-tool iprof pro‐
gram 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
SEE ALSO
Functions: atom_application_instrumentation(5), atom_application_navi‐
gation(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)