 |
Index for
Section 5 |
|
 |
Alphabetical
listing for A |
|
 |
Bottom of
page |
|
atom_description_file(5)
NAME
atom_description_file - Description of an Atom tool's instrumentation and
analysis files.
DESCRIPTION
An Atom tool's description file identifies and describes the tool's
instrumentation and analysis files. It can also specify the flags to be
used by the cc, ld, and atom commands when it is compiled, linked, and
invoked. Each Atom tool must supply at least one description file. See
atom(1) for additional information on Atom.
You must place a tool's description files, along with its instrumentation
and analysis files, in the tool's directory. By default, Atom searches for
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.
Atom has two types of description files:
· A description file providing an environment for generalized use of the
tool. A tool can provide only one general-purpose environment. The
name of this type of description file has the format: tool.desc.
· A description file providing an environment for use of the tool in
specific contexts, such as in a multithreaded application or in kernel
mode. A tool can provide several special-purpose environments, each of
which has its own description file. The name of this type of
description file has the format: tool.environment.desc.
The names supplied for the tool and environment portions of these names
correspond to values the user specifies with the -tool and -env flags on an
atom command when invoking the tool.
An Atom description file is a text file containing a series of tag, value
pairs. The tag and value are separated by white space and occupy a single
line. The order of the lines in a description file are unimportant. Lines
starting with a pound sign (#) are comments, blank lines are ignored. A
line can be continued by ending with a backslash (\) newline character.
The following tag values are defined. If a tool's description file contains
an unknown tag, Atom issues a warning and ignores that tag's line.
Duplicate tags in a description file cause a fatal error.
_________________________________________________________________
Tag Meaning
_________________________________________________________________
INST_FILE
The tool's instrumentation file. This tag is
required in all description files. The file can be
either a C source file (with a .c suffix) or an
object module (with an .o suffix). No other file
types are allowed.
ANAL_FILE
The tool's analysis file. If this is not
specified, a null analysis file is used. The file
can be either a C source file (with a ".c" suffix)
or an object module (with a ".o" suffix). No other
file types are allowed.
INST_CFLAGS
Flags to be passed to the C compiler when
compiling the instrumentation file. This tag is
ignored if the instrumentation file is not a C
source file.
ANAL_CFLAGS
Flags to be passed to the C compiler when
compiling the analysis file. This tag is ignored
if the analysis file is not specified, or is not a
C source file.
INST_LDFLAGS
Flags to be passed to the linker when linking the
instrumentation file with the Atom run-time
system.
ANAL_LDFLAGS
Flags to be passed to the linker when linking the
analysis file to resolve all undefined symbols.
ATOM_REQ
Required atom command line flags for the tool
described by this description file. These flags
are implicitly passed to Atom when the tool is
invoked. If the user specifies a conflicting flag,
the atom command displays a warning and ignores
the user-specified switch.
ATOM_DEF
Default atom command line flags for the tool
described by this description file. These flags
are implicitly passed to Atom when the tool is
invoked. If the user specifies a conflicting flag,
the atom command overrides the corresponding flag
listed in this list.
_________________________________________________________________
The following description file is for a tool named pixie that has an
instrumentation file called pixie.inst.c and an analysis file called
pixie.anal.c. The instrumentation file links in the libmld library (using
the -lmld flag) and the analysis file links in the pdf library (using the
-lpdf flag).
#
# pixie.desc
#
INST_FILE pixie.inst.c
ANAL_FILE pixie.anal.c
INST_LDFLAGS -lmld
ANAL_LDFLAGS -lpdf
The following environment-specific description file supports a version of
the pixie tool for the threads environment. The threaded version of pixie
uses the same instrumentation and analysis source files as the general-
purpose version. However, the source files are compiled with the -DTHREADS
compiler flag.
#
# pixie.threads.desc
#
INST_FILE pixie.inst.c
ANAL_FILE pixie.anal.c
INST_CFLAGS -DTHREADS
ANAL_CFLAGS -DTHREADS
INST_LDFLAGS -lmld
ANAL_LDFLAGS -lpdf
The following general-purpose description file for the third Atom tool
specifies default and required atom command line flags. It forces the
-heapbase progend flag to be passed to atom whenever the third tool is
invoked. It also passes the -A1 flag to the atom command line unless the
user overrides this option by explicitly specifying -A0 when issuing the
command.
#
# third.desc
#
INST_FILE third.inst.o
ANAL_FILE third.anal.o
ATOM_REQ -heapbase progend
ATOM_DEF -A1
-----------------------------------------------------------------
SEE ALSO
Commands: atom(1)
Functions: atom_application_instrumentation(5),
atom_application_navigation(5), atom_application_query(5),
atom_application_symbols(5), atom_instrumentation_routines(5),
atom_object_management(5), AnalHeapBase(5), Thread(5), Xlate(5)
Programmer's Guide
|
Index for
Section 5 |
|
|
Alphabetical
listing for A |
|
 |
Top of
page |
|