*** UNIX MANUAL PAGE BROWSER ***

atom(1) General Commands Manual 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...] 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. PARAMETERS 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 Digital UNIX. Multi-threaded programs linked on Digital UNIX V3.2 are not sup- ported, because the thread support libraries are not compatible with atom. Name of a C source file (with a .c suffix) or an object module (with a .o suffix) that contains the Atom tool's instrumentation proce- dures. 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, you should con- sider 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 (with a .c suffix) or an object module (with a .o suffix) that contains the Atom tool's analysis procedures. Analysis routines may per- form 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 com- mand with a -r option. OPTIONS The first format of the atom command is used to create a tool that in- struments 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 ac- cepts 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 de- scription 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 di- rectories. You can add directories to the search path by supplying a colon-separated list of additional directories to the ATOMTOOLPATH en- vironment 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 en- vironment 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 de- scription 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 li- braries in the shared executable. Allows debugging of instrumentation routines. Atom puts the control in dbx with a stop at the instrumenta- tion routine. See the Programmer's Guide for a discussion on how to use dbx with Atom. 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 -in- cobj option are. Excludes the named shared library from instrumenta- tion. 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 automati- cally instruments parts of libpthread.so even if it is specified in the -excobj option. Produces the instrumented program with debugging in- formation. 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 de- bugging of application routines. Changes the base of the analysis heap. This option has three forms: Sets the base to the given hex ad- dress. Sets the base to a default 31-bit address that is safe for ap- plications 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 pro- gram, you may have to choose a new location for the analysis heap. In- struments 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 multi-threaded program, this func- tion will advise the tool not to instrument certain threads-related sy- sem libraries even if they are selected. This ensures that the analysis is thread-safe. 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 di- rectory 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. Names the exe- cutable output file filename. By default, when the first format of the atom command is used, the file is called progname.toolname, or prog- name.toolname.environ if the -env environ option is used. When the sec- ond format of the atom command is used, the file is called prog- name.atom. 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 li- braries. 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 ig- nored. This is the default. 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 op- tions to the analysis file's compilation phase. Passes the specified options to the instrumentation file's compilation phase. 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 you specify the -Ldir option, Atom searches the given directory be- fore 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. After you have instrumented an application that uses shared libraries, set the LD_LIBRARY_PATH environment variable to point to the directory containing the instrumented shared libraries. Typically, this would be the current directory or the directory specified by the -shlibdir op- tion. You may leave LD_LIBRARY_PATH pointing to this directory while running other, uninstrumented applications. 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. EXAMPLES atom -tool third program Invokes Atom's Third Degree tool to instrument program, produc- ing the executable output file program.third. atom program myinst.c myanal.c Instruments program using the instrumentation file myinst.c and analysis file myanal.c, producing the executable output file program.atom. 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: Standard C Library (libc.a) routines (including system calls) can be called except for: unwind(3) routines and other exception-han- dling routines pthread_atfork tis(3) routines. Also, the standard I/O routines have certain differences in be- havior as described later in this section. 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 rou- tines that assume a particular environment (for example, X and Motif) may not be useful or correct in an Atom analysis environ- ment. 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 Ob- jAfter 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 un- buffered 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. PREPACKAGED TOOLS The following prepackaged tools can be named with the -tool option: tab(@); lfHB lfHB lw(1.5i) lw(3.0i). _ Tool@Description _ third@T{ Performs memory access checks and detects memory leaks in an application. See third(5). T} hiprof@T{ Produces a flat profile of an application that shows the exe- cution time spent in a given procedure, and a hierarchical profile that shows the execution time spent in a given procedure and all its descen- dents. See hiprof(5). T} pixie@T{ Produces a profile of an application - by procedure, source line, or instruction - by partitioning it into basic blocks and count- ing the number of times each basic block is executed. See pixie(5). T} _ EXAMPLE TOOLS The following example tools can also 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: tab(@); lfHB lfHB lw(1.5i) lw(3.0i). _ Tool@Description _ branch@T{ Instruments all conditional branches to determine how many are predicted correctly. T} cache@T{ Determines cache miss rate. Simulates execution of the appli- cation in 8KB direct-mapped cache. T} dtb@T{ Determines the number of dtb (data translation buffer) misses. Simulates execution of the application in 8KB pages and with a fully associative translation buffer. T} dyninst@T{ Provides fundamental dynamic counts of instructions, loads, stores, blocks, and procedures. T} inline@T{ Identifies potential candidates for inlining. T} iprof@T{ Prints the number of times each procedure is called as well as the number (dynamic count) of instructions executed by each procedure. T} malloc@T{ Records each call to the malloc function and prints a summary of the application's allocated memory. T} prof@T{ Prints the number (dynamic count) of instructions executed by each procedure, in a thread-safe manner. T} ptrace@T{ Prints the name of each procedure as it is called. T} trace@T{ 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. T} _ SEE ALSO Atom tools: third(5), hiprof(5), pixie(5) Equivalent driver commands: third(1), hiprof(1), pixie(1). Functions: atom_application_instrumentation(5), atom_application_navi- gation(5), atom_application_query(5), atom_application_resolvers(5), atom_description_file(5), atom_object_management(5), atom_instrumenta- tion_routines(5), AnalHeapBase(5), Xlate(5) Programmer's Guide delim off atom(1)