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

metric:counting_modes

event_group:counting_modes

metric_group_name:counting_modes

event_set:counting_modes

Parameters

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).

event_set_number:counting_modes

event_group_number:counting_modes

Exit Status

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

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.

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

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

pm_hpmcount1

pm_hpmcount1,pm_hpmcount2,pm_basic

HPM_L2_LATENCY 12 
HPM_EVENT_SET  5

The following output files are used.