Hardware performance monitor APIs and tools

Edit online

The bos.pmapi fileset contains libraries and tools that are designed to provide access to some of the counting facilities of the Performance Monitor feature included in select IBM® microprocessors.

They include the following:

  • The pmapi library, which contains a set of low-level application programming interfaces, APIs, includes the following:
    • A set of system-level APIs to permit counting of the activity of a whole machine or of a set of processes with a common ancestor.
    • A set of first party kernel-thread-level APIs to permit threads to count their own activity.
    • A set of third party kernel-thread-level APIs to permit a debug program to count the activity of target threads.
  • The pmcycles command, which returns the processor clock and decrementer speeds.
  • The pmlist command, which displays information about processors, events, event groups and sets, and derived metrics supported.
  • The hpm and hpm_r libraries, which contain a set of high-level APIs that enable the following:
    • Nested instrumentation of sections of code
    • Automatic calculation of derived metrics, and gathering of operating system resource-consumption metrics in addition to the raw hardware counter values
  • The hpmstat command, which collects the hardware performance monitor raw and derived metrics concerning total system activity of a machine.
  • The hpmcount command, which executes applications and provides the applications' execution wall clock time, the raw and derived hardware performance monitor metrics and the operating system resource-utilization statistics.
Note: The APIs and the events available on each of the supported processors have been completely separated by design. The events available, their descriptions, and their current testing status (which are different on each processor) are in separately installable tables, and are not described here because none of the API calls depend on the availability or status of any of the events.

The status of an event, as returned by the pm_initialize API initialization routine, can be verified, unverified, caveat, broken, group-only, thresholdable, or shared (see Performance monitor accuracy about testing status and event accuracy).

An event filter (which is any combination of the status bits) must be passed to the pm_initialize routine to force the return of events with status matching the filter. If no filter is passed to the pm_initialize routine, no events will be returned.