pm_get_data_pgroup, pm_get_tdata_pgroup and pm_get_Tdata_pgroup Subroutine

Purpose

Returns Performance Monitor data for the counting group to which a target pthread belongs.

Library

Performance Monitor APIs Library (libpmapi.a)

Syntax

#include <pmapi.h>

int pm_get_data_pgroup (pid,  tid,  ptid,  *pmdata)
pid_t pid;
tid_t tid;
ptid_t ptid;
pm_data_t *pmdata;

int pm_get_tdata_pgroup (pid, tid, *pmdata, *time)
pm_data_t *pmdata;
pid_t pid;
tid_t tid;
ptid_t ptid;
timebasestruct_t *time;

int pm_get_Tdata_pgroup (pid, tid, *pmdata, * times)
pm_data_t *pmdata;
pid_t pid;
tid_t tid;
ptid_t ptid;
pm_accu_time_t *times;

Description

The pm_get_data_pgroup subroutine retrieves the current Performance Monitor data for the counting group to which a target pthread belongs. The pthread must be stopped and must be part of a debuggee process under the control of the calling process.

The pm_get_tdata_pgroup subroutine retrieves the current Performance Monitor data for the counting group to which a target pthread belongs, and a timestamp indicating the last time the hardware counters were read.

The pm_get_Tdata_pgroup subroutine retrieves the current Performance Monitor data for the counting group to which a target pthread belongs, and the accumulated time (timebase, PURR time and SPURR time) the events were counted.

If the pthread is running in 1:1 mode, only the tid parameter must be specified. If the pthread is running in m:n mode, only the ptid parameter must be specified. If both the ptid and tid parameters are specified, they must be referring to a single pthread with the ptid parameter specified and currently running on a kernel thread with specified tid parameter.

The Performance Monitor data is always a set (one per hardware counter on the machine used) of 64-bit values. The information returned also includes the characteristics of the group, such as the number of its members, if it is a process level group, and if its counters are consistent with the sum of the counters for all of the pthreads in the group.

Parameters

Item Description
pid Process identifier of a target thread. The target process must be an argument of a debug process.
tid Thread ID of target pthread. To ignore this parameter, set it to 0.
ptid Pthread ID of the target pthread. To ignore this parameter, set it to 0.
*pmdata Pointer to a structure to return the Performance Monitor data for the group to which the target pthread belongs.
*time Pointer to a structure containing the timebase value the last time the hardware Performance Monitoring counters were read. This can be converted to time using the time_base_to_time subroutine.
*times Pointer to a structure containing the accumulated time (timebase, PURR time and SPURR time) the events were counted. Each time counter can be converted to time using the time_base_to_time subroutine.

Return Values

Item Description
0 No errors occurred.
Positive error code Refer to the pm_error Subroutine to decode the error code.

Error Codes

Refer to the pm_error Subroutine.

Files

Item Description
/usr/include/pmapi.h Defines standard macros, data types, and subroutines.