hpcproftt correlates `flat' profile metrics with either source code structure or object code and generates textual output suitable for a terminal. Alternatively, it also generates textual dumps of profile files.
hpcproftt [--source] [options] profile-file...
hpcproftt --object [options] profile-file...
hpcproftt --dump profile-file...
hpcproftt correlates `flat' profile metrics with either source code structure (the first and default mode) or object code (second mode) and generates textual output suitable for a terminal (hence the tt, for teletype, in its name). In both of these modes, hpcproftt expects a list of flat profile files. hpcproftt also supports a third mode in which it generates textual dumps of profile files. In this mode, the profile list may contain either flat or call path profile files.
hpcproftt defaults to source code correlation mode. Without any mode switch, it behaves as if passed --source=pgm,lm.
Source Source Structure Correlation. First, hpcproftt creates raw metrics for every native event with in each profile file. Derived summary metrics can be optionally created with the --metric option. All metrics are normalized to use the unit 'events' rather than 'samples' since this enables meaningful comparisons and derived metrics. Since percents facilitate rapid comprehension (compared to values), all raw metrics display as percents; derived metrics likewise default to percent, if sensible.
Then, hpcproftt correlates metrics to program structure. If hpcstruct(1) structure information is available, this is used for correlation; if not, a simple 'File | Procedure | Statement' structure is computed using the load module's line map.
Finally, hpcproftt generates metric summaries and annotated source files to standard out. Each metric summary compares a certain source structure element (such as a procedure) with all other elements of that type across the whole program. Structure elements include: Program, Load Module, File, Procedure, Loop (requires hpcstruct(1) ), and Statement. For example, the procedure summary shows (exclusive) metric values for each procedure in the program. (Structure elements are pruned if all corresponding metrics are 0.) Summaries are rank ordered by the first metric. hpcproftt optionally annotates source files with Statement (line) level metrics. Note that it can only annotate files found by combining debug information with --include search paths.
Object Correlation.
hpcproftt's object correlation mode is intended for inspection of fine-grained correlation. In contrast to the source structure correlation mode, true summaries are not computed; rather (like an annotated source file) hpcproftt generates annotated object code, i.e., procedures and instructions. Moreover, only raw metrics corresponding to the native events in one profile file may be correlated to the object code touched by those metrics. Accordingly, hpcproftt creates raw metrics for every native event in one profile file. Metrics use the unit 'samples' rather than 'events' and default to percents, though absolute values may optionally be displayed. Procedures are pruned from the output if no associated metric totals to the provided threshold.
Warnings:
Default values for an option's optional arguments are shown in {}.
Note: With multiple search-directory arguments, it may be the case that file f exists within more than one search directory. In this case, the ambiguity is resolved in favor of the search directory that appears first on the command line.
Use this option when a profile or binary contains references to files that have been relocated, such as might occur with a file system change.
hpcproftt --src --metric=sum poissonSolve.hpcrun*
hpcproftt --obj poissonSolve.hpcrun*
Version: 5.3.2-r4197 of 2012/04/19.
Nathan Tallent
Rice HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: http://hpctoolkit.org.