CVINSTR(1)CVINSTR(1)NAMEcvinstr - add WorkShop Performance instrumentation code to a program
SYNOPSIScvinstr [ options ] in_prog_name
DESCRIPTIONcvinstr 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.
Page 1
CVINSTR(1)CVINSTR(1)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 ALSOcvperf(1)BUGScvinstr cannot handle stripped programs; it will give a message warning
the user if it is invoked on a stripped executable.
Page 2
