cvinstr(1)

NAME
     cvinstr - add WorkShop Performance instrumentation code to a program

SYNOPSIS
     cvinstr [ options ] in_prog_name

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

     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.
CVINSTR OPTIONS
     -[no]verbose
          Set verbose mode; cvinstr will print out detailed information to the
          .Log file. Default:  -verbose

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

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

     -[no]bbcounts
          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.

     -[no]branchcounts
          Generate a count bin for each taken branch in the program.  Default:
          -branchcounts

SEE ALSO
     cvperf(1)

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