psprocess
Performance Analysis Post-Processing

Overview

psprocess is a PerfSuite command-line utility that can be used to post-process the results of a performance analysis experiment. The current version supports experiments produced by the libpshwpc library, either directly or by using the command-line utility psrun.

psprocess can produce either plain-text or HTML-formatted results, under user control through command-line options. Here are examples of each:

Using psprocess

Before you use psprocess, you should already have generated one or more XML output files using either the PerfSuite command-line utility psrun or by running a program that contains calls to the PerfSuite library libpshwpc. Either of these methods will create an XML file containing the hardware performance counter data obtained during a run of your application that can then be used as input to psprocess.

Manual Page

NAME

psprocess - pre- and post-processing utility for PerfSuite

SYNOPSIS

psprocess [option] file ...

DESCRIPTION

psprocess is a pre- and post-processing utility for XML documents created by other PerfSuite tools. The behavior and output of psprocess is dependent not only on options supplied by the user, but by the type of XML document contained in file. You can determine the XML document type by examining the first few lines of the input file. psprocess currently supports the following document types:

<hwpcreport>: A "hardware performance report" generated either by the tool psrun or through direct use of the libpshwpc library. Reports generated in either "counting mode" or "profiling mode" are supported.
<multihwpcreport>: A "multiple hardware performance report" generated by a prior invocation of psprocess using the "combine" option -c and supplying one or more <hwpcreport> files as input.

OPTIONS

General:

-a, --annotate: Specify annotation string (must also use -c)
-c, --combine: Operate in combine mode
-h, --help: Display brief help
-o, --output FILE: Specify output file name (default stdout)
-V, --version: Report psprocess version number

hwpcreport:

-b, --brief: Brief output (no machine information)

hwpcreport (counting mode):

-H, --html: Generate XHTML using XSLT
-m, --metrics FILE: Specify custom metric definition file (text output only)

hwpcreport (profiling mode):

-e, --executable FILE: Specify executable
--progress: Display progress
-s, --show LIST: Select what to report. LIST is a comma-separated list of "modules", "files", "functions", "lines"
-t, --threshold NUM: Set minimum % to report
-x, --xmlout: Produce XML as output
--vmon: Produce VProf-compatible output

multihwpcreport (counting mode):

-C, --csv: Comma-separated value output
-P, --peak MFLOPS: Specify peak per-CPU MFLOPS

multihwpcreport (profiling mode):

--vmon: Produce VProf-compatible output

ENVIRONMENT

PS_CXXFILT: Specify an alternate C++ name demangling utility (default c++filt). IA-64 only, or if PerfSuite was configured and built without support for BFD (--disable-binutils).
PS_CXXFILTSTYLE: Specify an alternate C++ demangling style (default installation-dependent). IA-64 only, or if PerfSuite was configured and built without support for BFD.
PS_HWPC_METRICS: Specify a custom metric definition file to add to psprocess's predefined derived metrics. Predefined metrics that are used by default are located in the directory share/perfsuite/xml/pshwpc (relative to the top-level PerfSuite installation directory).
LANG: Specify an alternate language/locale.

NOTES

To map program counter address to source code line numbers (for "profiling mode" reports), psprocess uses either the GNU BFD library directly (IA-32) or an external addr2line process (IA-64). psprocess is written in the Tcl scripting language using PerfSuite Tcl C extensions.