hpmstat Command

Edit online

Purpose

Provides system-wide hardware performance counter information.

Syntax

hpmstat [ -b time_base ] [ -d ] [ -D metrics ] [ -O options ] [ -g event_groups ] [ -H ] [ -k ] [ -m metrics_groups ] [ -o file ] [ -r ] [ -s set ] [ -T ] [ -U ] [-u ] [ -x ] [ -@ ALL | WparName ] interval count
hpmstat [-h]

Description

The hpmstat command provides the execution wall clock time, hardware performance counters information, and derived hardware metrics. Only a user with root privilege can use the hpmstat command.

When specified without command-line options, hpmstat command counts the default 1 iteration of user, kernel, and hypervisor (for processors that supports hypervisor mode) activity for 1 second for the default set 1 of events. It then writes the raw counter values and derived metrics to standard output. By default, runlatch is disabled so that counts can be performed while executing in idle cycle.

When the -U option is specified, interval is in microseconds, the iteration count is infinity, and derived metrics are not calculated and written to standard output. This option is ignored if the counter multiplexing mode is specified.

When the -T option is specified, output information is preceded by the timestamp (seconds plus microseconds) and timing information is written as timestamps instead of time in seconds.

Event types to be monitored and the associated hardware performance counters are specified by using either the set -s option or by specifying an event group name or set number in the HPM_EVENT_SET environment variable. Alternatively, specify counter and event pairs (POWER3 and PowerPC 604 RISC Microprocessor) or an event group name (POWER4 and later) in the libHPM_events input file (takes precedence over HPM_EVENT_SET). A counting mode can qualify each set. 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, a counting mode can qualify each event group.

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 set number value to 0.

Valid event set numbers run from 1 to a higher limit dependent upon the processor type, which can be listed by using the pmlist command.

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

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 operation allows the user to select all the derived metrics that pertains to the specified groups. A counting node qualifies each metric group.

When counting in multiplexing mode, the results must be normalized before being used. The default base that is 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 by using the HPM_NORMALIZE environment variable.

When you run the hpmstat command from the global workload partition (WPAR), it is possible to monitor a specific WPAR by using the -@ WparName option. You can use the -@ ALL option to monitor all active WPARs in the system and to retrieve per-WPAR data.

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

Flags

Item Description
-@ ALL | WparName Selects the target WPAR in which the activity is to be measured. The ALL value means that the hpmstat command measures all active WPARs in the system and reports the activity for each WPAR. This option is only available when you run the hpmstat command from the global WPAR.
-b time_base Selects a base for the data normalization. Following are the available bases:
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. A counting mode can qualify each derived metric by using the following option: 
metric:counting_modes
(See the -m option for available counting modes.)
-O options The -O option can have the following values:
threshold_cmp_val=value
Sets a threshold-compare floating point value.

The Power® processor has a threshold counter facility. The threshold counter is different from the primary performance monitor counters (PMCs) because the threshold counter can count the number of events that occur between a separate set of designated start events and end events from the core, cache, and memory subsystems.

This option specifies a threshold value that you can use to compare against the number of events between the designated start events and end events.

threshold_event_sel=name
Specifies the events that must be considered for threshold counting. Following are the valid values for the threshold_event_sel option:
THRESHOLD_COUNT_CYCLES
Counts the number of events that occur or cycles on which the control register run latch is set. The AIX® operating system uses the control register bit to indicate the idle or run state. The performance monitoring unit (PMU) also use this bit to avoid counting events during idle periods. This bit is commonly called the run latch. This option does not depend on freeze conditions. This option means that the events are counted even when the PMU froze the contents of event counters.
THRESHOLD_COUNT_NUM_COMP_INSTR
Counts the number of completed instructions when the control register run latch is set.

This option does not depend on freeze conditions. This option means that the events are counted even when the PMU froze the contents of event counters.

THRESHOLD_COUNT_PMC1_EVENTS
Counts the PMC1 events.

PMC1 - PMC4 are 32-bit registers that are called programmable counters because the events that can be counted are specified by the program. This option depends on freeze conditions. This option means that the events are not counted when the PMU froze the contents of event counters.
-O options (continued)
THRESHOLD_COUNT_PMC2_EVENTS
Counts the PMC2 events. This option depends on freeze conditions. This option means that the events are not counted when the PMU froze the contents of event counters.
THRESHOLD_COUNT_PMC3_EVENTS
Counts the PMC3 events. This option depends on freeze conditions. This option means that the events are not counted when the PMU froze the contents of event counters.
THRESHOLD_COUNT_PMC4_EVENTS
Counts the PMC4 events. This option depends on freeze conditions. This option means that the events are not counted when the PMU froze the contents of event counters.
threshold_eve_start_sel=name
Specifies the event to start the threshold counting. For valid values of this option, see threshold_eve_stop_sel.
-O options (continued)
threshold_eve_stop_sel=name
Specifies the event to stop the threshold counting. You can set the following values for the threshold_eve_start_sel and threshold_eve_stop_sel options:
PM_MRK_INST_DECODED
Sampled instructions are decoded.
PM_MRK_INST_DISP
Sampled instructions are dispatched.
PM_MRK_INST_ISSUED
Sampled instructions are issued.
PM_MRK_INST_FIN
Sampled instructions are finished.
PM_MRK_INST_CMPL
Sampled instructions are completed.
PM_MRK_LD_MISS_L1
Sampled instruction level 1 (L1) load cache is missed.
PM_MRK_L1_RELOAD_VALID
Sampled instruction level 1 (L1) reload is valid.
EVE_SEL_PMC1
Event that is selected in monitor mode control register (MMCR) 1 for PMC1 occurred.
EVE_SEL_PMC2
Event that is selected in MMCR1 for PMC2 occurred.
EVE_SEL_PMC3
Event that is selected in MMCR1 for PMC3 occurred.
EVE_SEL_PMC4
Event that is selected in MMCR1 for PMC4 occurred.
PM_MRK_NTF_FIN
Sampled instruction is in the next to finish state.
PM_MRK_L2_RC_DISP
RC machine that is dispatched for sampled instruction.
PM_MRK_ST_DONE_L2
RC machine that is done for sampled instruction.
-O options (continued)
random_samp_ele_crit=name
Specifies the random criteria for selecting the instructions for sampling. Following are the valid values for this option:
ALL_INSTR
All instructions are eligible. This value is the default setting.
LOAD_STORE
The operation is routed to the Load Store Unit (LSU); for example, load, store.
PROB_NOP
Samples special no-operation instructions, which are called Probe NOP events.
LARX_STCX
Samples load and reserve indexed (LARX) instructions and store conditional indexed (STCX) instructions.
LOAD_SAMPLING
Samples load instructions.
LONG_LATENCY_OP
Samples long latency instructions (div/sqrt/mul).
STORE_SAMPLING
Samples store instructions.
LOAD_MISSES
Samples load-miss instructions.
LOAD_HIT_STORE
Samples load-hit-store instructions. This value is applicable only for cases where a load operation can forward data from the store queue to a finish state. This value is not applicable to cases where a load-hit-store instruction is in the store queue but the load operation partially overlaps with the store.
BRANCH_MISPREDICTS
Samples branch-mispredict instructions.
BRANCH_MISPREDICTS_DIR_CR_CTR
Samples branch-mispredict events (Direction, CR, or CTR).
BRANCH_MISPREDICTS_TA
Samples branch-mispredict events (TA).
BRANCHES_RESOLVED_TAKEN
Samples branches with resolution.
NON_REPEATING_BRANCHES
Samples nonrepeating branches.
ALL_BRANCHES_REQ_PRED
Samples all branches that require prediction.
-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. A counting mode can qualify each event group by using the following option: 
event_group:counting_modes
(See the -m option for available counting modes.)
-H Counts hypervisor activity only.
-h Displays help message.
-k Counts system activity only.
-m metrics_groups Selects a list of derived metric groups to be evaluated. The default derived metric group refers to all derived metrics that do not belong to a specific derived metric group. A counting mode can qualify each metric group by using the following option: 
metric_group_name:counting_modes
Following are the available counting modes:
u
user mode
k
kernel mode
h
hypervisor mode
r
runlatch mode
n
nointerrupt mode
-o file Output file name.
-r Enables runlatch and disables counts while executing in idle cycle.
-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. A counting mode can qualify each set by using the following option: 
event_set:counting_modes
(See the -m option for available counting modes.)
-T Writes timestamps instead of time in seconds.
-U Puts counting time interval in microseconds. This option is ignored if the counter multiplexing mode is specified.
-u Counts user activity only.
-x Displays results in VPA XML format.

Parameters

Item Description
interval Displays the counting time interval in seconds or microseconds, with a default value of 1.
count Shows the number of iterations to count. The default is 1 with an interval in seconds, and infinity when the option -U is specified.

Environment Variables

The following environment variables directly affect the execution of the hpmstat command (there are more 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 higher limit on POWER4 and later systems. This environment variable is also used to select an event group name on POWER4 and later systems. A counting mode can qualify each event set by using the following option: 
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. A counting mode can qualify each event group by using the following option: 
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. A counting mode can qualify each metric group. The -m option takes precedence over this variable.
HPM_PMD_METRIC Specifies a comma-separated list of derived metrics. A counting mode can qualify each derived metric. 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.
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 that is used for the time slice duration is 100 ms.
In addition, the following environment variables that are 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 that are 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: 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 that are associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

  1. To write information for system, user, and hypervisor activity over a 1-second interval that concerns events in set 2 from hardware counters, enter the following command: 
    hpmstat -s 2
  2. To write information for the user activity that concerns events of group 0 and the system activity that concerns events of group 1 for the wpar1 WPAR over a five-second interval, enter the following command: 
    hpmstat -@ wpar1 -g 0:u,1:k 5
  3. To count the number of threshold count events that are elapsed between a distinct pair of threshold start events and end events and to specify the threshold value for comparison, enter the following command: 
    hpmstat -g 607 -O threshold_cmp_val=10000 -O
threshold_event_sel=THRESHOLD_COUNT_CYCLES -O
threshold_eve_start_sel=PM_MRK_L1_RELOAD_VALID -O
threshold_eve_stop_sel=PM_MRK_ST_DONE_L2 -O
random_samp_ele_crit=ALL_INSTR

Location

/usr/bin/perf/pmapi/hpmstat

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 that are specified with the -s option. The format for a POWER3 andPowerPC 604 RISC Microprocessor counter and 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
For a POWER4 event group name, the format is event_group_name. For example: 
pm_hpmcount1
HPM_flags.env File containing environment variable and value pairs that are used for the computation of derived metrics. For example: 
HPM_L2_LATENCY 12 
HPM_EVENT_SET  5

The following output files are used.

Item Description
file File specified with the -o option for hpmstat command output results.