Running DCPI -- A DCPI "one pager" / PJD / 16 August 2001

Is DCPI the right tool?
  CPU related or memory access related problem? Yes.
  Thread related problem? Use Visual Threads.
  I/O related problem? Use iostat, vmstat, collect, etc.
  Resource scheduling problem? Use iostat, vmstat, collect.
  Need a call graph? Use Hiprof.

DCPI uses sampling to collect data about programs as they execute. This data is
provided by special registers in the Alpha processor hardware. The DCPI data
collection subsystem periodically reads this data from those registers and
stores it in a database. Sample data is organized by epoch (the time period in
which data was collected), process ID and executable image. DCPI collects data
about programs that run during an epoch giving the developer a system-wide view
of execution. Once profile data has been collected, it can be analyzed and
displayed using any of several analytical tools. Collection and analysis takes
seven steps:
  1 Create a directory for the DCPI database (mkdir)
  2 Create an environment variable, DCPIDB, to remember the path to the
    DCPI database (setenv)
  3 Become the superuser (su)
  4 Start the DCPI data collection subsystem (dcpid)
  5 Run the application program to be analyzed
  6 Stop the data collection subsystem (dcpiquit)
  7 Use the DCPI analytical tools to analyze/display profile information,
    identify components for further study, and then drill down (dcpiprof,
    dcpilist, dcpitopcounts)

The session transcript below shows these seven steps. The command lines are
numbered, e.g., "1 >" and the numbers correspond to the steps outlined above.
    1 > mkdir /dsk0h/dcpidb
    2 > setenv DCPIDB /dsk0h/dcpidb
    3 > su
    Password:
    4 > dcpid $DCPIDB
    dcpid: load   : loaded pcount driver
    dcpid: monitoring pm
    dcpid: monitoring cycles
    dcpid: logging to /dsk0h/dcpidb/dcpid-positron.log
    5 > ecm4c.test 1000000 63844855 < big_number
    Found probable prime factor of 27 digits: 241421225374647262615077397
    6 > dcpiquit
    dcpictl: quit successful
    7 > dcpiprof -i -pm retired -event cycles

The last command (number 7) displays an image-by-image summary showing the
number of retired instruction samples and the number of processor cycle samples
per image. ("Retired" means "successfully completed.") The summary shows where
the most time was spent (cycles) and which images executed the most
instructions (retires.) Images with a large number of cycles and retires are
possible candidates for improvement.

The next step is to drill down further and display statistics for the
procedures in the hottest images. This can be accomplished with the command:
    dcpiprof -pm retired -event cycles <<image>>
where <<image>> is the name of the executable program image to be investigated.
This displays the number of retired instruction samples and the number of
processor cycle samples per procedure. Procedures with a large number of cycles
and retires are possible candidates for improvement. Use the command:
    dcpilist -pm retired -event cycles <<procedure>> <<image>>
to display retired instructions and cycles for a particular procedure in an
image. Source code can be displayed with or instead of annotated disassembly:
    dcpilist -both -pm ret -event cycles <<procedure>> <<image>>
    dcpilist -source -pm ret -event cycles <<procedure>> <<image>>