|
|
atom_description_file(5)
Contents
|
atom_description_file - Description of an Atom tool's
instrumentation and analysis files.
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 suffix) or an
object module (with an 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
-----------------------------------------------------------------
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
atom_description_file(5)
[ Back ] |
