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.

Security

Attention RBAC users and Trusted AIX® users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Example

To run the ls command and write information concerning events in set 5 from hardware counters, enter:
```
hpmcount -s 5 ls
```
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
```
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.