atom(1) — Commands
NAME
atom − Builds an instrumented version of an application program
SYNOPSIS
atom appl_prog −tool toolname [−env environ] [flags...]
atom appl_prog instrum_file [anal_file] [flags...]
PARAMETERS
appl_progFile name of a fully linked shared or nonshared executable.
instrum_fileName of a C source file (with a .c suffix) or an object module (with a .o suffix) that contains the Atom tool’s instrumentation procedures. 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 flag. By convention, most instrumentation files have the suffix .inst.c or .inst.o.
If you pass an object module for this parameter, you should consider compiling the module with either the −g1 or −g flags. If there are errors in your instrumentation procedures, Atom can issue more complete diagnostic messages when the instrumentation procedures are thus compiled.
anal_fileName 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. 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 flag. By convention, most analysis files have the suffix .anal.c or .anal.o.
FLAGS
The first format of the atom command uses a prepackaged tool to build an instrumented version of an application program. This format requires the −tool flag and accepts the −env flag. It allows neither the instrum_file nor the anal_file parameter.
The following list describes those flags used to invoke Atom with a prepackaged tool:
−tool toolname
Identifies the prepackaged Atom tool to be used. By default, atom searches for prepackaged tools 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. The set of environments supported by a given tool is defined by the tool’s creator and listed in the tool’s documentation. Atom displays an error if you specify an environment that is undefined for the tool. Some tools allow you to omit the −env flag to obtain a general-purpose environment.
The second format of the atom command is used to create a tool that instruments an application program. This format requires the instrum_file parameter and accepts the anal_file parameter.
Both formats of the atom command accepts the following flags. Note that the listed default values apply only to the second format. When the −tool flag is specified, required atom flags, as well as the default values of atom, compiler, and linker flags may be defined by the specified Atom tool.
−A0Indicates that calls to analysis routines are not to be optimized. This is the default.
−A1Optimizes 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.
−allInstruments all statically loaded shared libraries in the shared executable.
−debugAllows 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.
−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 flag or an −incobj flag. Those libraries specified to the −dynobj flag are not instrumented; those specified to the −incobj flag are.
−excobj objname
Excludes the named shared library from instrumentation. You can use the −excobj flag more than once to specify several shared libraries. Note that the Third Degree Atom tool instruments the memory allocation functions in libc.so and libcxx.so. Similarly, when −env threads is specified, Atom automatically instruments parts of libpthreads.so even if it’s specified in the −excobj flag.
−gProduces the instrumented program with debugging information. This enables debugging of analysis routines. The default −A0 option (not −A1) is recommended when −g 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.
−incobj objname
Instruments the named shared library. You can use the −incobj flag more than once to specify several shared libraries.
−LdirChanges 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.
−LChanges 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.
−o filenameNames the executable output file filename. By default, when the first format of the atom command is used, the file is called progname.toolname, or progname.toolname.environ if the -env environ flag is used. When the second format of the atom command is used, the file is called progname.atom.
−shlibdir dirname
Specifies an existing directory to which atom writes the instrumented shared libraries. Using this flag 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 flag, 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.
−vDisplays each step Atom takes to create the instrumented program.
−versionDisplays Atom’s version number.
−wnControls display of warning messages. The value of n can be one of the following values:
0Display all warning messages, including those that are normally suppressed.
1Suppress warning messages that can be safely ignored. This is the default.
−Wla,flag1[,flag2][,flag3]...
Passes the specified flags to the analysis file’s link phase.
−Wli,flag1[,flag2][,flag3]...
Passes the specified flags to the instrumentation file’s link phase.
−Wca,flag1[,flag2][,flag3]...
Passes the specified flags to the analysis file’s compilation phase.
−Wci,flag1[,flag2][,flag3]...
Passes the specified flags to the instrumentation file’s compilation phase.
DESCRIPTION
When invoked with the −tool flag, the atom command uses a prepackaged tool to build an instrumented version of an application program. This format requires the −tool flag and accepts the −env flag. It allows neither the instrum_file nor the anal_file parameter.
The following are the names of supported prepackaged tools that are accepted by the −tool flag:
| Tool | Description |
| third | Performs memory access checks and detects memory leaks in an application. |
| hiprof | Produces a flat profile of an application that shows the execution time spent in a given procedure, and a hierarchical profile that shows the execution time spent in a given procedure and all its descendents. |
| pixie | Produces a profile of an application − by procedure, source line, or instruction − by partitioning it into basic blocks and counting the number of times each basic block is executed. |
The following are the names of unsupported example tools that are accepted by the −tool flag:
| 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. |
| ptrace | Prints the name of each procedure as it is called. |
| 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. |
The second format of the atom command takes an application program, instrumentation file, and analysis file as input, and produces an instrumented application program executable. You cannot use the −tool and −env flags with this format. This format requires the instrum_file parameter and accepts the anal_file parameter.
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 flag, Atom searches the given directory before searching the default locations. You can specify multiple −Ldir flags. You can also supply the −L flag without a directory name. This causes Atom to avoid searching the default directories. Only those directories specified by −Ldir flags 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 flag. 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 applications that have been instrumented. As long you choose a unique suffix name (using the −suffix flag) 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
1.atom -tool third program
Invokes Atom’s Third Degree tool to instrument program, producing the executable output file program.third.
2.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
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.
Atom does not work on programs built with the −om compiler flags.
ERRORS
The diagnostic messages produced by Atom are sent to the standard error file.
RELATED INFORMATION
Commands:
dxprof(1), dxheap(1) (dxprof(1) and dxheap(1) are available only if the Developer’s Tool Kit and associated reference pages are installed on your system.)
Atom Tools: third(5), hiprof(5), pixie(5)
Functions: atom_application_instrumentation(5), atom_application_navigation(5), atom_application_query(5), atom_application_resolvers(5), atom_description_file(5), atom_object_management(5), atom_instrumentation_routines(5), AnalHeapBase(5), Xlate(5)
Programmer’s Guide