pmapi.h File

Purpose

Describes the structures and constants used by the Performance Monitor APIs subroutines.

Syntax

#include <pmapi.h>

Description

The pmapi.h file defines the following symbolic constants, types, and structures:

Symbolic Constants

Item Description
MAX_COUNTERS Maximum number of supported counters
MIN_THRESH_VALUE Minimum threshold value
MAX_THRESH_VALUE Maximum threshold value
COUNT_NOTHING Specifies to not count event

Constants for event filters

Item Description
PM_VERIFIED Specifies events that have been verified
PM_UNVERIFIED Specifies events that have not been verified
PM_CAVEAT Specifies events that work with caveats
PM_GET_GROUPS Not a filter; specifies that supported event groups are to be returned by pm_init.
Constants for Processor Idents
Item Description
PM_CURRENT Specifies that the PMAPI is to be initialized for the current processor type.
PM_PowerPC®604 Specifies that supported events for the PowerPC®604 are to be returned.
PM_PowerPC®604e Specifies that supported events for the PowerPC604e are to be returned.
PM_RS64_II Specifies that supported events for the RS64-II are to be returned.
PM_POWER3 Specifies that supported events for the POWER3 are to be returned.
PM_RS64_III Specifies that supported events for the RS64-III are to be returned.
PM_POWER3_II Specifies that supported events for the POWER3-II are to be returned.
PM_POWER4 Specifies that supported events and/or groups for the POWER4 are to be returned.
PM_MPC7450 Specifies that supported events for the MPC7450 are to be returned
PM_POWER4_II Specifies that supported events and/or groups for the POWER4-II are to be returned.
PM_POWER5 Specifies that supported events and/or groups for the POWER5 are to be returned.
PM_PowerPC 970 Specifies that supported events and/or groups for the PowerPC 970 are to be returned.
PM_POWER6® Specifies that supported events and/or groups for the POWER6® are to be returned.
PM_PPowerPC 970MP Specifies that supported events and/or groups for the PowerPC 970MP are to be returned.
PM_POWER7® Specifies that supported events and/or groups for the POWER7® are to be returned.
POWER8® Specifies that supported events and/or groups for the POWER8® are to be returned.
POWER9™ Specifies that supported events and/or groups for the POWER9 are to be returned.
PM_MAXPROCTYPE Maximum number of processor idents.

Constants for setting mode bits

Item Description
PM_PROCTREE Turns process tree counting on
PM_COUNT Turns counting on immediately
PM_USER Turns user mode counting on
PM_KERNEL Turns kernel mode counting on
PM_PROCESS Creates a process level group
The structure pm_info_t contains the following members: 
int             maxpmcs             number of available counters
int             *maxevents          number of events for each hw counter 
pm_events_t     **list_events       list of available events 
int             thresholdmult       threshold multiplier 
char            *proc_name          processor name
int             hthresholdmult      upper threshold multiplier

The structure pm_events_t contains the following members:

int             event_id            event number 
char            status              'v': verified 
                                    'u': unverified
                                    'c': caveat
char            threshold           'y': thresholdable 
                                    'g': group-only
                                    'G': thresholdable group-only
char            *short_name          mnemonic name 
char            *long_name           long name 
char            *description         full description
The structure pm_info2_t contains the following members: 
int              maxpmcs             number of available counters
int              *maxevents          number of events for each hw counter 
pm_events2_t     **list_events       list of available events 
int              thresholdmult       threshold multiplier 
int              hthresholdmult      upper threshold multiplier
int              Hthresholdmult      hyper threshold multiplier
char             *proc_name          processor name
pm_feature_t     proc_feature        processor feature list
The structure pm_events2_t contains the following members: 
int              event_id            event number 
pm_status_t      status              event status 
char             *short_name         mnemonic name 
char             *long_name          long name 
char             *description        full description
The structure pm_status_t contains the following members: 
unsigned:1       b.unverified        unverified event
unsigned:1       b.verified          verified event
unsigned:1       b.caveat            event verified with some caveat(see description)
unsigned:1       b.group_only        event can only be used within a group
unsigned:1       b.threshold         event can be used with a threshold
unsigned:1       b.shared            event is shared between hardware threads
unsigned:1       b.support_mode      support user, kernel, hypervisor and proctree counting modes applied
unsigned:1       b.overflow          generate an interrupt on overflow
unsigned:1       b.marked            marked event
The structure pm_feature_t contains the following members: 
unsigned:1       b.hypervisor        hypervisor counting mode is supported
The structure pm_groups_info_t contains the following members: 
  int            maxgroups          number of available groups
  pm_groups_t    *event_groups      list of event groups
The structure pm_groups_t contains the following members: 
  int            group_id           group number
  int            *events            events in this group, by ID #
  char           *short_name        mnemonic name
  char           *long_name         long name
  char           *description       full description
The structure pm_prog_t contains the following members: 
unsigned:6       mode.b.threshold        threshold value 
unsigned:1       mode.b.thresh_res       uses upper threshold mutiplier if set
unsigned:1       mode.b.thresh_hres      uses hyper threshold mutiplier if set
unsigned:1       mode.b.nointerrupt      interrupt counting disable
unsigned:1       mode.b.runlatch         runlatch enable/disable
unsigned:1       mode.b.is_group         is an event group
unsigned:1       mode.b.process          process level group indicator 
unsigned:1       mode.b.hypervisor       turns hypervisor mode counting on
unsigned:1       mode.b.kernel           turns kernel mode counting on 
unsigned:1       mode.b.user             turns user mode counting on 
unsigned:1       mode.b.count            counting state 
unsigned:1       mode.b.proctree         turns process tree counting on
unsigned:1       mode.b.shared           turns multiplexing on
int              events[MAX_COUNTERS]    list of counted events
Note: The mode.b.shared flag must be set by the user.
The structure pm_data_t contains the following members: 
pm_ginfo_t       ginfo                 group information 
long long        accu[MAX_COUNTERS]    accumulated data
The structure pm_ginfo_t contains the following members: 
int              members;              number of threads in group 
unsigned:1       flags.b.process       process level group indicator 
unsigned:1       flags.b.consistent    group data consistent with members
The structure pm_accu_time_t contains the following members: 
timebasestruct_t  accu_timebase       accumulated time base
timebasestruct_t  accu_purr           accumulated PURR time
timebasestruct_t  accu_spurr          accumulated SPURR time
Type for timeslice: 
typedef    int         pm_events_prog_t[MAX_COUNTERS] array of counted events
The structure pm_prog_mx_t contains the following members: 
unsigned:6             mode.b.threshold        threshold value
unsigned:1             mode.b.thresh_res       uses upper threshold mutiplier if set
unsigned:1             mode.b.thresh_hres      uses hyper threshold mutiplier if set
unsigned:1             mode.b.runlatch         runlatch enable/disable
unsigned:1             mode.b.is_group         is an event group
unsigned:1             mode.b.process          process level group indicator
unsigned:1             mode.b.hypervisor       turns hypervisor mode counting on
unsigned:1             mode.b.kernel           turns kernel mode counting on
unsigned:1             mode.b.user             turns user mode counting on
unsigned:1             mode.b.count            counting state
unsigned:1             mode.b.proctree         turns process tree counting on
int                    slice_duration          duration of each time slice in ms
int                    nb_events_prog          number of counted event sets
pm_events_prog_t       *events_set;            array of counted event sets
unsigned:1             mode.b.shared           turns multiplexing on
Note: The mode.b.shared flag must be set by the user.
The structure pm_prog_mm_t contains the following members: 
int            proctree               turns process tree counting on
int            slice_duration         duration of each time slice in ms
int            nb_set_prog            number of counted event sets
pm_prog_t      *prog_set;             array of counted event sets / counting mode
The structure pm_accu_mx_t contains the following members: 
timebasestruct_t    accu_time               accumulated time
timebasestruct_t    accu_purr               accumulated PURR time
timebasestruct_t    accu_spurr              accumulated SPURR time
long long           accu_data[MAX_COUNTERS] accumulated data
The structure pm_data_mx_t contains the following members: 
pm_ginfo_t     ginfo         group information
int            nb_accu_mx    number of data accumulator sets
int            nb_mx_round   number of loops on all the event sets
pm_accu_mx_t   *accu_set     array of data accumulator sets
The structure pm_wpar_ctx_info_t contains the following members: 
cid_t           cid                           WPAR ID
char            name[MAXCORRALNAMELEN + 1]    WPAR name
pm_wp_handle_t  hwpar                         WPAR opaque handle (unique identifier)
The profiler_type_t enum contains the following members:
P_THREAD = 0
P_THREAD_GROUP

typedef pm_accu_mx_t pm_accu_t;
The pm_data_time_t structure contains the following members:
int                 nb_accu;              number of data accumulator sets 
int		    nb_mx_round;	   number of loops on all the event sets 
timebasestruct_t    total_active_time;    total time the context is active and competing for PMU 
timebasestruct_t    total_active_purr;    total PURR time the context is active and competing for PMU
timebasestruct_t    total_active_spurr;   total SPURR time the context is active and competing for PMU
timebasestruct_t    total_profiled_time;  total time the context got the PMU
timebasestruct_t    total_profiled_purr;  total PURR time the context got the PMU 
timebasestruct_t    total_profiled_spurr; total SPURR time the context got the PMU
pm_ginfo_t          ginfo;                group information   
pm_accu_t           *accu_set;            array of data accumulator sets
The following are declared as functions: 
double pm_cycles(void)
void   pm_error(char *where, int error)
int    pm_get_proctype()

int    pm_init(int filter, pm_info_t *pminfo, pm_groups_info_t *pmgroupsinfo)
int    pm_initialize(int filter, pm_info2_t *pminfo, pm_groups_info_t *pmgroups, int proctype)
 
int    pm_set_program(pm_prog_t *prog)
int    pm_set_program_wp(cid_t cid, pm_prog_t *prog)
int    pm_get_program(pm_prog_t *prog)
int    pm_get_program_wp(cid_t cid, pm_prog_t *prog)
int    pm_start(void)
int    pm_tstart(timebasestruct_t *time)
int    pm_start_wp(cid_t cid)
int    pm_tstart_wp(cid_t cid, timebasestruct_t *time)
int    pm_stop(void)
int    pm_tstop(timebasestruct_t *time)
int    pm_stop_wp(cid_t cid)
int    pm_tstop_wp(cid_t cid, timebasestruct_t *time)
int    pm_reset_data(void)
int    pm_reset_data_wp(cid_t cid)
int    pm_get_data(pm_data_t *data)
int    pm_get_tdata(pm_data_t *data, timebasestruct_t *time)
int    pm_get_Tdata(pm_data_t *data, pm_accu_time_t *time)
int    pm_get_data_wp(pm_wp_handle_t wp_handle, pm_data_t *data)
int    pm_get_tdata_wp(pm_wp_handle_t wp_handle, pm_data_t *data)
int    pm_get_Tdata_wp(pm_wp_handle_t wp_handle, pm_data_t *data)
int    pm_get_data_cpu(int cpuid, pm_data_t *data)
int    pm_get_tdata_cpu(int cpuid, pm_data_t *data, timebasestruct_t *time)
int    pm_get_Tdata_cpu(int cpuid, pm_data_t *data, pm_accu_time_t *time)
int    pm_get_data_lcpu(int lcpuid, pm_data_t *data)
int    pm_get_tdata_lcpu(int lcpuid, pm_data_t *data, timebasestruct_t *time)
int    pm_get_Tdata_lcpu(int lcpuid, pm_data_t *data, pm_accu_time_t *time)
int    pm_get_data_lcpu_wp(pm_wp_handle_t wp_handle, int lcpuid, pm_data_t *data)
int    pm_get_tdata_lcpu_wp(pm_wp_handle_t wp_handle, 
                            int lcpuid, pm_data_t *data, timebasestruct_t *time)
int    pm_get_Tdata_lcpu_wp(pm_wp_handle_t wp_handle, 
                            int lcpuid, pm_data_t *data, pm_accu_time_t *time)
int    pm_get_wplist(const char *name, pm_wpar_ctx_info_t *wp_list, int *size)
int    pm_delete_program(void)
int    pm_delete_program_wp(cid_t cid, pm_prog_t *prog)
 
int    pm_set_program_mythread(pm_prog_t *prog)
int    pm_get_program_mythread(pm_prog_t *prog)
int    pm_start_mythread(void)
int    pm_tstart_mythread(timebasestruct_t *time)
int    pm_stop_mythread(void)
int    pm_tstop_mythread(timebasestruct_t *time)
int    pm_reset_data_mythread(void)
int    pm_get_data_mythread(pm_data_t *data)
int    pm_get_tdata_mythread(pm_data_t *data, timebasestruct_t *time)
int    pm_get_Tdata_mythread(pm_data_t *data, pm_accu_time_t *time)
int    pm_delete_program_mythread(void)
 
int    pm_set_program_thread(pid_t pid, tid_t tid, pm_prog_t *prog)
int    pm_get_program_thread(pid_t pid, tid_t tid, pm_prog_t *prog)
int    pm_start_thread(pid_t pid, tid_t tid)
int    pm_tstart_thread(pid_t pid, tid_t tid, timebasestruct_t *time)
int    pm_stop_thread(pid_t pid, tid_t tid)
int    pm_tstop_thread(pid_t pid, tid_t tid, timebasestruct_t *time)
int    pm_reset_data_thread(pid_t pid, tid_t tid)
int    pm_get_data_thread(pid_t pid, tid_t tid, pm_data_t *data)
int    pm_get_tdata_thread(pid_t pid, tid_t tid, pm_data_t *data, timebasestruct_t *time)
int    pm_get_Tdata_thread(pid_t pid, tid_t tid, pm_data_t *data, pm_accu_time_t *time)
int    pm_delete_program_thread(pid_t pid, tid_t tid)
 
int    pm_set_program_mygroup(pm_prog_t *prog)
int    pm_get_program_mygroup(pm_prog_t *prog)
int    pm_start_mygroup(void)
int    pm_tstart_mygroup(timebasestruct_t *time)
int    pm_stop_mygroup(void)
int    pm_tstop_mygroup(timebasestruct_t *time)
int    pm_reset_data_mygroup(void)
int    pm_get_data_mygroup(pm_data_t *data)
int    pm_get_tdata_mygroup(pm_data_t *data, timebasestruct_t *time)
int    pm_get_Tdata_mygroup(pm_data_t *data, pm_accu_time_t *time)
int    pm_delete_program_mygroup(void)
 
int    pm_set_program_group(pid_t pid, tid_t tid, pm_prog_t *prog)
int    pm_get_program_group(pid_t pid, tid_t tid, pm_prog_t *prog)
int    pm_start_group(pid_t pid, tid_t tid)
int    pm_tstart_group(pid_t pid, tid_t tid, timebasestruct_t *time)
int    pm_stop_group(pid_t pid, tid_t tid)
int    pm_tstop_group(pid_t pid, tid_t tid, timebasestruct_t *time)
int    pm_reset_data_group(pid_t pid, tid_t tid)
int    pm_get_data_group(pid_t pid, tid_t tid, pm_data_t *data)
int    pm_get_tdata_group(pid_t pid, tid_t tid, pm_data_t *data, timebasestruct_t *time)
int    pm_get_Tdata_group(pid_t pid, tid_t tid, pm_data_t *data, pm_accu_time_t *time)
int    pm_delete_program_group(pid_t pid, tid_t tid)

int    pm_set_program_pthread(pid_t pid, tid_t tid,  ptid_t ptid, pm_prog_t *prog)
int    pm_set_program_pgroup(pid_t pid, tid_t tid, ptid_t ptid, pm_prog_t *prog)
int    pm_get_program_pthread(pid_t pid, tid_t tid, ptid_t ptid, pm_prog_t *prog)
int    pm_get_program_pgroup(pid_t pid, tid_t tid, ptid_t ptid, pm_prog_t *prog)
int    pm_start_pthread(pid_t pid, tid_t tid, ptid_t ptid)
int    pm_tstart_pthread(pid_t pid, tid_t tid, ptid_t ptid,timebasestruct_t *time)
int    pm_start_pgroup(pid_t pid, tid_t tid, ptid_t ptid)
int    pm_tstart_pgroup(pid_t pid, tid_t tid, ptid_t ptid,timebasestruct_t *time)
int    pm_stop_pthread(pid_t pid, tid_t tid, ptid_t ptid)
int    pm_tstop_pthread(pid_t pid, tid_t tid, ptid_t ptid,timebasestruct_t *time)
int    pm_stop_pgroup(pid_t pid, tid_t tid, ptid_t ptid)
int    pm_tstop_pgroup(pid_t pid, tid_t tid, ptid_t ptid,timebasestruct_t *time)
int    pm_reset_data_pthread(pid_t pid, tid_t tid,  ptid_t ptid)
int    pm_reset_data_pgroup(pid_t pid, tid_t tid,  ptid_t ptid)
int    pm_get_data_pthread(pid_t pid, tid_t tid, ptid_t ptid, pm_data_t *data)
int    pm_get_tdata_pthread(pid_t pid, tid_t tid, ptid_t ptid, pm_data_t *data,
           timebasestruct_t *time)
int    pm_get_Tdata_pthread(pid_t pid, tid_t tid, ptid_t ptid, pm_data_t *data, 
           pm_accu_time_t *time)
int    pm_get_data_pgroup(pid_t pid, tid_t tid, ptid_t ptid, pm_data_t *data)
int    pm_get_tdata_pgroup(pid_t pid, tid_t tid, ptid_t ptid, pm_data_t *data,
           timebasestruct_t *time)
int    pm_get_Tdata_pgroup(pid_t pid, tid_t tid, ptid_t ptid, pm_data_t *data, 
           pm_accu_time_t *time)
int    pm_delete_program_pthread(pid_t pid, tid_t tid,  ptid_t ptid)
int    pm_delete_program_pgroup(pid_t pid, tid_t tid,  ptid_t ptid) 

int    pm_set_program_mx(pm_prog_mx_t *prog)
int    pm_get_program_mx(pm_prog_mx_t *prog)
int    pm_set_program_mm(pm_prog_mm_t *prog)
int    pm_set_program_wp_mm(cid_t cid, pm_prog_mm_t *prog)
int    pm_get_program_mm(pm_prog_mm_t *prog)
int    pm_get_program_wp_mm(cid_t cid, pm_prog_mm_t *prog)
int    pm_get_data_mx(pm_data_mx_t *data)
int    pm_get_tdata_mx(pm_data_mx_t *data, timebasestruct_t *time)
int    pm_get_data_cpu_mx(int cpuid, pm_data_mx_t *data)
int    pm_get_tdata_cpu_mx(int cpuid, pm_data_mx_t *data, timebasestruct_t *time)
int    pm_get_data_lcpu_mx(int lcpuid, pm_data_mx_t *data)
int    pm_get_tdata_lcpu_mx(int lcpuid, pm_data_mx_t *data, timebasestruct_t *time)
int    pm_get_data_wp_mx(pm_wp_handle_t wp_handle, pm_data_mx_t *data)
int    pm_get_tdata_wp_mx(pm_wp_handle_t wp_handle, pm_data_mx_t *data, timebasestruct_t *time)
int    pm_get_data_lcpu_wp_mx(pm_wp_handle_t wp_handle, int lcpuid, pm_data_mx_t *data)
int    pm_get_tdata_lcpu_wp_mx(pm_wp_handle_t wp_handle, 
                               int lcpuid, pm_data_mx_t *data, timebasestruct_t *time)
int    pm_set_program_mythread_mx(pm_prog_mx_t *prog)
int    pm_get_program_mythread_mx(pm_prog_mx_t *prog)
int    pm_set_program_mythread_mm(pm_prog_mm_t *prog)
int    pm_get_program_mythread_mm(pm_prog_mm_t *prog)
int    pm_get_data_mythread_mx(pm_data_mx_t *data)
int    pm_get_tdata_mythread_mx(pm_data_mx_t *data, timebasestruct_t *time)

int    pm_set_program_thread_mx(pid_t pid, tid_t tid, pm_prog_mx_t *prog)
int    pm_get_program_thread_mx(pid_t pid, tid_t tid, pm_prog_mx_t *prog)
int    pm_set_program_thread_mm(pid_t pid, tid_t tid, pm_prog_mm_t *prog)
int    pm_get_program_thread_mm(pid_t pid, tid_t tid, pm_prog_mm_t *prog)
int    pm_get_data_thread_mx(pid_t pid, tid_t tid, pm_data_mx_t *data)
int    pm_get_tdata_thread_mx(pid_t pid, tid_t tid, pm_data_mx_t *data, 
          timebasestruct_t *time)
 
int    pm_set_program_mygroup_mx(pm_prog_mx_t *prog)
int    pm_get_program_mygroup_mx(pm_prog_mx_t *prog)
int    pm_set_program_mygroup_mm(pm_prog_mm_t *prog)
int    pm_get_program_mygroup_mm(pm_prog_mm_t *prog)
int    pm_get_data_mygroup_mx(pm_data_mx_t *data)
int    pm_get_tdata_mygroup_mx(pm_data_mx_t *data, timebasestruct_t *time)
 
int    pm_set_program_group_mx(pid_t pid, tid_t tid, pm_prog_mx_t *prog)
int    pm_get_program_group_mx(pid_t pid, tid_t tid, pm_prog_mx_t *prog)
int    pm_set_program_group_mm(pid_t pid, tid_t tid, pm_prog_mm_t *prog)
int    pm_get_program_group_mm(pid_t pid, tid_t tid, pm_prog_mm_t *prog)
int    pm_get_data_group_mx(pid_t pid, tid_t tid, pm_data_mx_t *data)
int    pm_get_tdata_group_mx(pid_t pid, tid_t tid, pm_data_mx_t *data, 
           timebasestruct_t *time)

int    pm_set_program_pthread_mx(pid_t pid, tid_t tid, ptid_t ptid, pm_prog_mx_t *prog)
int    pm_set_program_pgroup_mx(pid_t pid, tid_t tid, ptid_t ptid, pm_prog_mx_t *prog)
int    pm_get_program_pthread_mx(pid_t pid, tid_t tid, ptid_t ptid, pm_prog_mx_t *prog)
int    pm_get_program_pgroup_mx(pid_t pid, tid_t tid, ptid_t ptid, pm_prog_mx_t *prog)
int    pm_set_program_pthread_mm(pid_t pid, tid_t tid, ptid_t ptid, pm_prog_mm_t *prog)
int    pm_set_program_pgroup_mm(pid_t pid, tid_t tid, ptid_t ptid, pm_prog_mm_t *prog)
int    pm_get_program_pthread_mm(pid_t pid, tid_t tid, ptid_t ptid, pm_prog_mm_t *prog)
int    pm_get_program_pgroup_mm(pid_t pid, tid_t tid, ptid_t ptid, pm_prog_mm_t *prog)
int    pm_get_data_pthread_mx(pid_t pid, tid_t tid, ptid_t ptid, pm_data_mx_t *data)
int    pm_get_tdata_pthread_mx(pid_t pid, tid_t tid, ptid_t ptid, 
           pm_data_mx_t *data, timebasestruct_t *time)
int    pm_get_data_pgroup_mx(pid_t pid, tid_t tid, ptid_t ptid, 
           pm_data_mx_t *data)
int    pm_get_tdata_pgroup_mx(pid_t pid, tid_t tid, ptid_t ptid, 
           pm_data_mx_t *data, timebasestruct_t *time)
int    pm_get_data_generic ( pid_t pid, tid_t tid, ptid_t ptid, 
           profiler_type_t prof_type, pm_data_time_t *data)