HP DCPI tool

dcpix(1)

NAME

dcpix - Instrument a program to get basic block and edge counts.

SYNOPSIS

dcpix myprog [-conservative]

DESCRIPTION

Dcpix is similar to pixie except that it measures executions of both basic blocks and edges between them.

Dcpix is used in conjunction with stall analysis tools (dcpicalc(1), dcpitopstalls(1), dcpiwhatcg(1)). Normally, these tools must estimate execution counts of basic blocks and edges. These estimates are sometimes inaccurate.

For deterministic programs, one can measure the execution counts using dcpix and supply the results to stall analysis tools. The program must be deterministic because it must be run twice: once under dcpix to measure execution counts, and once under dcpid(1) to gather sample data.

By default, dcpix instruments only a set of blocks and edges that is sufficient for computing counts for all blocks and edges by exploiting flow constraints. However, this is inaccurate for programs that call longjmp (or similar routines). With the -conservative flag, dcpix adds instrumentation to every block.

TYPICAL USAGE

  dcpix myprog		% creates myprog.dcpix and myprog.tab
  myprog.dcpix		% creates myprog.xct
  dcpicalc -tab myprog.tab -xct sum.xct -db db myprocedure myprog

To analyze the performance of multiple runs of myprog, one can do either:

  dcpicalc -tab myprog.tab -xct myprog1.xct \
           -xct myprog2.xct ... -xct myprogN.xct \
	   -db db myprocedure myprog

or:

  dcpisumxct myprog1.xct myprog2.xct ... -xct myprogN.xct -o sum.xct
  dcpicalc -tab myprog.tab -xct sum.xct -db db myprocedure myprog

Using dcpisumxct(1) is more efficient when running dcpicalc multiple times, e.g., on several procedures in the same program.

IMPLEMENTATION

Dcpix is an atom tool that instruments all edges exiting a branching block plus the entry block(s) of each procedure. These measured counts are more than enough to calculate counts for every block using "flow in = flow out" constraints, unless your program executes an infinite loop.

ENVIRONMENT

If the environment variable DCPIX_ADDPID is set, the instrumented program (e.g., myprog.dcpix) will append its pid to the names of .xct files. Thus, running the instrumented program multiple times shouldn't cause one run to overwrite the .xct file from a previous run.

LIMITATIONS

Dcpix has no locking, so it is inaccurate for multi-threaded code. Also, it does not support programs that call fork().

Some single-threaded programs have nondeterministic implementations, e.g., implementations that uses ld_l/st_c. Thus, the count for some blocks may differ when you run myprog under dcpid and myprog.dcpix to generate the counts files.

The stall analysis tools currently introduce round-off errors into the measured counts because it represents them as multiples of the sampling period.

SEE ALSO

dcpi(1), dcpi2bb(1), dcpi2pix(1), dcpi2ps(1), dcpicalc(1), dcpicat(1), dcpicc(1), dcpicoverage(1), dcpictl(1), dcpid(1), dcpidiff(1), dcpidis(1), dcpiepoch(1), dcpiflow(1), dcpiflush(1), dcpikdiff(1), dcpilabel(1), dcpildlatency(1), dcpilist(1), dcpiprof(1), dcpiprofileme(1), dcpiquit(1), dcpiscan(1), dcpisource(1), dcpistats(1), dcpisumxct(1), dcpitar(1), dcpitopcounts(1), dcpitopstalls(1), dcpiuninstall(1), dcpiupcalls(1), dcpivarg(1), dcpivcat(1), dcpiversion(1), dcpivlst(1), dcpivprofiler(1), dcpiwhatcg(1), dcpiformat(4), dcpiexclusions(4)

For more information, see the DCPI project home page http://h30097.www3.hp.com/dcpi.

COPYRIGHT

Copyright 1996-2004, Hewlett-Packard Company. All rights reserved.