unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



atom(1)								      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 instru-
  ments	an application program.	This format requires the instrum_file parame-
  ter. The analysis_file parameter is optional,	because	Atom can be used just
  to examine a program statically, in which case no run-time analysis rou-
  tines	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	sim-
  ple tool_name. This format requires the -tool	option and accepts the -env
  option.  It allows neither the instrum_file nor the analysis_file parame-
  ter.

  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 direc-
      tories. 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 exe-
      cutable.

  -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.

  -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 instru-
      mentation	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 instru-
      mented; 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.

  -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 applica-
      tion (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 applica-
	  tions	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 pro-
      gram, you	may have to choose a new location for the analysis heap.

  -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 multi-threaded program, this	func-
      tion will	advise the tool	not to instrument certain threads-related
      sysem libraries even if they are selected. This ensures that the
      analysis is thread-safe.

  -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.

  -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 writ-
      ten 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	whi-
      tespace characters to separate arguments from their parameters (if any)
      and from other arguments.

      If you need to represent spaces within a -toolargs argument, use match-
      ing single-quotes	or matching double-quotes, making sure that you	avoid
      having the shell interpret those characters as shell-special charac-
      ters.  For example:


	   -toolargs="-exc 'strstreambase::strstreambase(char*,	int, char*)'"

	   -toolargs='-exc "operator -"	-exc "ostream::operator	<&lt;<&lt;" \
		      -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 rou-
	  tines.

  -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 multi-
      threaded programs, run ld(1) and atom(1) on the same version of Tru64
      UNIX. Multi-threaded programs linked on DIGITAL UNIX V3.2	are not	sup-
      ported, 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 instrumen-
      tation 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 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 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 rou-
  tine 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 else-
  where, 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 generat-
  ing 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 environ-
       ment.

  The standard I/O library provided to analysis	routines does not automati-
  cally	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	rou-
  tine -- 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 rou-
  tines	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 non-shared	pro-
  grams, 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 suf-
  fix. 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 applica-
  tions	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 deter-
	    mine 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 asso-
	    ciative translation	buffer.
  dyninst

	    Provides fundamental dynamic counts	of instruc-
	    tions, 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 instruc-
	    tions executed by each procedure, in a thread-
	    safe manner.
  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.
  __________________________________________________________

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

  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), Thread(5),	Xlate(5)

  Programmer's Guide