 |
Index for
Section 1 |
|
 |
Alphabetical
listing for A |
|
 |
Bottom of
page |
|
atom(1)
NAME
atom - Builds an instrumented version of an application program
SYNOPSIS
atom 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.
-tool 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.
-env environ
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.
-A0 Indicates that calls to analysis routines are not to be optimized. This
is the default.
-A1 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.
-all
Instruments all statically loaded shared libraries in the shared
executable.
-debug
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.
-errstring
Specifies a string for use when reporting errors or warnings. By
default, the string "atom:" appears on all error or warning messages.
-ladebug
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.
-dynobj objname
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.
-excobj objname
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.
-fork
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.
-ga (-g)
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.
-gap
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.
-gp Produces the instrumented program with debugging information. This
enables debugging of application routines.
-gpa
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.
-heapbase [hex_address | taso | progend]
Changes the base of the analysis heap. This option has three forms:
-heapbase hex_address
Sets the base to the given hex address.
-heapbase taso
Sets the base to a default 31-bit address that is safe for
applications that expect analysis addresses to fit in 31 bits.
-heapbase progend
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.
-ii 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).
-incobj objname
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.
-keep
Indicates that the temporary files that Atom creates should be placed
in the current working directory, and not deleted when instrumentation
is complete.
-Ldir
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.
-L 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.
-libdyn
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.
-loadpath
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.
-map
Produces a list of the starting addresses of the sections in the
instrumented executable.
-noclruniq
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.
-nofini
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.
-o filename
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.
-pthread
Specifies that thread-safe support is required. This option should be
used when instrumenting threaded applications.
-shlibdir dirname
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.
-suffix suffix
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.
-toolargs="arg1 arg2 ..."
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)"'
-v Displays each step Atom takes to create the instrumented program.
-version
Displays Atom's version number.
-wn Controls display of warning messages. The value of n can be one of the
following values:
0 Display all warning messages, including those that are normally
suppressed.
1 Suppress warning messages that can be safely ignored. This is the
default.
2 Suppress warning messages emitted when processing analysis
routines.
3 Suppresses warning messages about shared library processing errors.
Atom ignores shared libraries that cannot be processed.
-Wla,option1[,option2][,option3]...
Passes the specified options to the analysis file's link phase.
-Wli,option1[,option2][,option3]...
Passes the specified options to the instrumentation file's link phase.
-Wca,option1[,option2][,option3]...
Passes the specified options to the analysis file's compilation phase.
-Wci,option1[,option2][,option3]...
Passes the specified options to the instrumentation file's compilation
phase.
OPERANDS
appl_prog
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.
instrum_file
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 .o 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.
analysis_file
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 .o 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 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.
NOTES
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.
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 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 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 .atom
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.
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
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
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
application procedure from an analysis routine.
__________________________________________________________
EXAMPLES
1. This example invokes the iprof example tool to instrument program,
producing the executable output file program.iprof.
atom -tool iprof program
2. 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_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
|
Index for
Section 1 |
|
|
Alphabetical
listing for A |
|
 |
Top of
page |
|