*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> cvinstr (1)              


CVINSTR(1)							    CVINSTR(1)

NAME    [Toc]    [Back]

     cvinstr - add WorkShop Performance	instrumentation	code to	a program

SYNOPSIS    [Toc]    [Back]

     cvinstr [ options ] in_prog_name

DESCRIPTION    [Toc]    [Back]

     cvinstr is	a program which	reads an executable program, and writes	an
     equivalent	program	containing additional instrumentation code used	for
     performance measurment of the executable.	The additional code either
     maintains an array	of counts representing the number of times various
     elements of the program are executed, or the number of statistical
     samples that found	the PC at various values, or both.  If the target
     program uses dynamic shared libraries, they are also instrumented.

     Normally, cvinstr is invoked during the data collection phase of WorkShop
     Performance tools;	it is not intended to be explicitly invoked by a user.

     Options are available: (a)	to specify that	cvinstr	count executions of
     each call-site in the program and the first block in each function	only;
     (b) to specify execution counts for all basic blocks within the program;
     and/or (c)	to instrument to enable	statistical PC sampling	for the
     program.  Any combination of these	options, or none of them may be

     In	the context of cvinstr,	a basic	block is a region of the program that
     can be entered only at the	beginning and exited only at the end; these
     are defined in terms of the instructions in the object program, not in
     terms of basic-blocks defined by the compiler in terms of the source
     code.  If basic block counting is specified, enough information is
     provided to compute exact instruction counts for the program and each of
     its functions, as well as to compute execution counts for each source
     line in the program.  If only function/call-site counts are taken,	these
     computations cannot be performed.

     A program instrumented for	full basic block counting will run
     approximately 2-3 times slower than the original; a program instrumented
     for function/call-site counting will run about 50-100% slower.  Actual
     slowdowns will vary with the nature of the	program.

     In	addition to the	instrumented executable	and its	libraries, cvinstr
     generates a Log file that summarizes various characteristics of the
     program and its shared libraries.	All files are written to a single
     directory,	named by the -D	argument to the	command.

     cvinstr supports the caching of instrumented Dynamic Shared Objects.
     When a DSO	is instrumented, it is saved in	the directory specified	by the
     environment variable CVINSTRLIB.  Experiment directories will contain
     symbolic links to the DSO cache directory.	 Caching is enabled by default
     and may be	turned off by the -noreuse and -noupdate options.

									Page 1

CVINSTR(1)							    CVINSTR(1)

	  Set verbose mode; cvinstr will print out detailed information	to the
	  .Log file. Default:  -verbose

	  Instrument the program to invoke PC sampling at start-up time.
	  Default:  -nopcsample

	  Generate counts for all call-sites and the first basic block of each
	  function only.  Default:  -nofcncounts

	  Generate function and	basic-block counts.  Default:  -bbcounts

     -D	output_directory
	  Specify a directory for writing the output file.  Default is current
	  directory, "./".

     -o	out_prog_name
	  Specify a name for the translation.  Default is to remove any
	  leading directory names from the in_prog_name	and append "_Instr" to
	  the name.

     The following options are provided	for use	by WorkShop/Tester.

     -coverage name
	  Name of the coverage file.  This is a	command	file where complex
	  selection critera can	be specified.  The ability to trace function
	  arguments and	function return	values is also provided.

	  Generate a count bin for each	taken branch in	the program.  Default:

SEE ALSO    [Toc]    [Back]


BUGS    [Toc]    [Back]

     cvinstr cannot handle stripped programs; it will give a message warning
     the user if it is invoked on a stripped executable.

									PPPPaaaaggggeeee 2222
[ Back ]
 Similar pages
Name OS Title
cvperf IRIX WorkShop Performance View
cvspeed IRIX The suite of WorkShop Performance Tools
cvprc IRIX file describing WorkShop performance tasks
cvexprnt IRIX print out the contents of WorkShop performance experiment records or data files
x11perfcomp Tru64 X11 server performance comparison program
x11perf Tru64 X11 server performance test program
AddCallObj Tru64 Allows an Atom tool's instrumentation routine to add, within an application program, calls to analys...
ReplaceEntry Tru64 Allows an Atom tool's instrumentation routine to add, within an application program, calls to analys...
GetInstBlock Tru64 Allows an Atom tool's instrumentation routine to find locations in an application program
GetEntryBlock Tru64 Allows an Atom tool's instrumentation routine to find locations in an application program
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service