hpmcount Command

Purpose

Measures application performance.

Syntax

hpmcount [ -a ] [ -b time_base ] [ -d ] [ -D metrics ] [ -g event_groups ] [ -H ] [ -k ] [ -m metrics_groups ] [ -o file ] [ -s set ] [-x ] command

hpmcount [-h]

Description

The hpmcount command provides the execution wall clock time, hardware performance counters information, derived hardware metrics, and resource utilization statistics (obtained from the getrusage() system call) for the application named by command.

Event types to be monitored and the associated hardware performance counters are specified by setting the -s option, by specifying an event group name, set number, or a comma-separated list of set numbers in the HPM_EVENT_SET environment variable, or by specifying counter/event pairs POWER3 / PowerPC 604 RISC Microprocessor) or an event group name (POWER4 and later) in the libHPM_events input file (takes precedence over HPM_EVENT_SET). Each set can be qualified by a counting mode. An event group number or name can be specified by setting the -g option or specifying a comma-separated list of event groups in the HPM_EVENT_GROUP environment variable. In the same manner, each event group can be qualified by a counting mode.

Valid event set numbers run from 1 to an upper limit dependent upon the processor type, which can be listed using the pmlist command. A comma-separated list of event sets can be specified instead of a set number, in which case the counter multiplexing mode is selected. To select all event sets, set the number value to 0.

A comma-separated list of derived metrics can be specified by setting the -D option. Each derived metric can be qualified by a counting mode.

A list of derived metric groups can be specified by setting the -m option or by specifying a comma-separated list of derived metric groups in the HPM_PMD_GROUP environment variable. This allows the selection of all of the derived metrics pertaining to the specified groups. Each metric group can be qualified by a counting mode.

System and hypervisor (for processors supporting hypervisor mode) activity can be included in counting by specifying the -k and -H options.

When counting in the multiplexing mode, the results must be normalized to be used. The default base used for the data normalization is the timebase. The -b option allows for the use of the PURR time or the SPURR time (when supported by the processor) for the data normalization. The base for the data normalization can also be defined using the HPM_NORMALIZE environment variable.

Results can be output in XML format using the -x option.

Flags

Item Description
-a Aggregates the counters on POE runs.
-b time_base Selects a base for the data normalization. The available bases are as follows:
time
timebase
purr
PURR time (when available)
spurr
SPURR time (when available)
The default value is time.
-d Adds detailed set counts for counter multiplexing mode.
-D metrics Selects a list of derived metrics to be evaluated. Each derived metric can be qualified by a counting mode as follows: 
metric:counting_modes
(See the -m option for available counting modes.)
-g event_groups Lists a predefined group of events or a comma-separated list of event group names or numbers. When a comma-separated list of groups is used, the counter multiplexing mode is selected. Each event group can be qualified by a counting mode as follows: 
event_group:counting_modes
(See the -m option for available counting modes.)
-H Adds hypervisor activity on behalf of the process.
-h Displays help message.
-k Adds system activity on behalf of the process.
-m metrics_groups Selects a list of derived metric groups to be evaluated. The derived metric group refers to all derived metrics that do not belong to a specific derived metric group. Each metric group can be qualified by a counting mode as follows: 
metric_group_name:counting_modes
The available counting modes are as follows:
u
user mode
k
kernel mode
h
hypervisor mode
r
runlatch mode
n
nointerrupt mode
-o file Output file name.
-s set Lists a predefined set of events or a comma-separated list of sets (1 to N, or 0 to select all. See the pmlist command.) When a comma-separated list of sets is used, the counter multiplexing mode is selected. Each set can be qualified by a counting mode as follows: 
event_set:counting_modes
(See the -m option for available counting modes.)
-x Displays results in XML format.

Parameters

Item Description
command Specifies the executed program for which performance measurements are made.

Environment Variables

The following environment variables directly affect the execution of the hpmcount command (there are additional MP_* environment variables that influence the execution of parallel programs).

Item Description
HPM_EVENT_SET Selects one of the event sets. The value can be an integer from 1 to 6 on POWER3 systems, 1 to 4 on PowerPC 604 RISC Microprocessor systems, or 1 to a processor-dependent upper limit on POWER4 and later systems. This environment variable is also used to select an event group name on POWER4 and later systems. A comma-separated list of event sets can be specified. In this case, the counter multiplexing mode is selected. Each event set can be qualified by a counting mode as follows: 
event_set_number:counting_modes
The -g or -s option takes precedence over this variable. The HPM_EVENT_GROUP environment variable takes precedence over this variable.
HPM_EVENT_GROUP Selects the event groups. A comma-separated list of event groups can be specified. In this case, the counter multiplexing mode is selected. Each event group can be qualified by a counting mode as follows: 
event_group_number:counting_modes
The -g or -s option takes precedence over this variable. The HPM_EVENT_GROUP environment variable takes precedence over the HPM_EVENT_SET variable.
HPM_NORMALIZE Provides the base to be used for the data normalization. The -b option takes precedence over this variable.
HPM_PMD_GROUP Specifies a comma-separated list of derived metric groups. Each metric group can be qualified by a counting mode. The -m option takes precedence over this variable.
HPM_PMD_METRIC Specifies a comma-separated list of derived metrics. Each derived metric can be qualified by a counting mode. The -D option takes precedence over this variable.
HPM_DIV_WEIGHT Provides a weight (an integer greater than 1) to be used to compute weighted flips on POWER4 systems.
MP_CHILD Used in a parallel environment when aggregate counts are specified to complement the output results file name (myID), synchronize collation of results, and identify verbose/debug diagnostic messages more closely.
MP_PROCS The number of program tasks.
HPM_AGGREGATE_OUTPUT Aggregates counts on POE applications (forces the command line argument -a). With this flag, a single file performance file is generated for all tasks. This only works with POE or Load Leveller, and it requires the availability of a parallel file system (such as GPFS™) on the system.
HPM_LOG_DIR When this flag is set, hpmcount writes a hpm_log.id file with the performance data in the provided directory. This is in addition to the regular output.
MP_PARTITION On POE applications, id is a POE ID provided by MP_PARTITION. Otherwise, it is the pid. Also names internal lock and data files.
HPM_MX_DURATION When counting in counter multiplexing mode, this flag specifies the duration of each slice of time. It is expressed in ms, and must lie in the range of 10 ms - 30 s. When this flag is not set, the default value used for the time slice duration is 100 ms.
In addition, the following environment variables, supplied by the user, specify estimations of memory, cache, and TLB miss latencies for the computation of derived metrics. These environment variables do not take precedence over the same estimations eventually provided in the file HPM_flags.env, if present.
  • HPM_MEM_LATENCY
  • HPM_L3_LATENCY
  • HPM_L35_LATENCY
  • HPM_AVG_L3_LATENCY
  • HPM_AVG_L2_LATENCY
  • HPM_L2_LATENCY
  • HPM_L25_LATENCY
  • HPM_L275_LATENCY
  • HPM_L1_LATENCY
  • HPM_TLB_LATENCY

Exit Status

Item Description
0 Successful completion.
>0 An error occurred.

Example

  1. To run the ls command and write information concerning events in set 5 from hardware counters, enter: 
    hpmcount -s 5 ls
  2. To run the ls command and write information concerning events in sets 5, 2, and 9 from hardware counters using the counter multiplexing mode, enter: 
    hpmcount -s 5,2,9 ls
  3. To run the ls command and report derived metrics pertaining to the default and cpi_breakdown metric groups counted respectively in kernel+user+hypervisor mode and user mode, enter: 
    hpmcount -m default:kuh,cpi_breakdown:u ls

Implementation Specifics

The hpmcount command uses the PMAPI thread-level API.

The hpmcount command parameter is not parsed as a command line for an application name with options. Instead, a shell script must be created that contains the command line.

Location

/usr/bin/perf/pmapi/hpmcount

Standard Input

Not used.

Standard Output

Performance monitoring results are written to stdout, unless the -o file option is specified on the command line.

Standard Error

Used only for diagnostic messages.

Files

The following input files are used if present.

Item Description
libHPM_events User-supplied event set file. This file does not take precedence over the command lines specified with the -s option. The format for a POWER3/PowerPC 604 RISC Microprocessor counter/event pair is counternumber eventname. For example: 
0 PM_LD_MISS_L2HIT 
1 PM_TAG_BURSTRD_L2MISS 
2 PM_TAG_ST_MISS_L2 
3 PM_FPU0_DENORM 
4 PM_LSU_IDLE 
5 PM_LQ_FULL 
6 PM_FPU_FMA 
7 PM_FPU_IDLE
A comma-separated list of events can also be specified. This turns on the counter multiplexing mode: 
0 PM_CYC,PM_FPU_FIN,PM_IC_MISS
1 PM_LD_CMPL,PM_INST_CMPL,PM_DC_MISS
2 PM_INST_CMPL,PM_FPU_WT,PM_INST_CMPL
3 PM_LD_MISS_DC_XU,PM_CYC,PM_CYC
For a POWER4 event group name, the format is event_group_name. For example: 
pm_hpmcount1
A comma-separated list of events can also be specified. This turns on the counter multiplexing mode: 
pm_hpmcount1,pm_hpmcount2,pm_basic
HPM_flags.env File containing environment variable/value pairs used for the computation of derived metrics. For example: 
HPM_L2_LATENCY 12 
HPM_EVENT_SET  5
./.hpm_lockfile_mp_partition Lock file. This file is reserved for the hpmcount command's internal use.
./.hpm_datafile_mp_partition Accumulative results file. This file is reserved for the hpmcount command's internal use.

The following output files are used.

Item Description
file_myID.pid File specified with the -o option for hpmcount output results, where myID is taken from the MP_CHILD environment variable, with a default value of 0000.
HPM_LOG_DIR/hpm_log.MP_PARTITION or HPM_LOG_DIR/hpm_log.pid Log file specified for aggregate counters on POE runs.
./.hpm_lockfile_mp_partition Lock file. This file is reserved for the hpmcount command's internal use.
./.hpm_datafile_mp_partition Accumulative results file. This file is reserved for the hpmcount command's internal use.