Initializes the Performance Monitor APIs.
Performance Monitor APIs Library (libpmapi.a)
#include <pmapi.h>
int pm_init ( filter, *pminfo, *pm_groups_info)
int filter;
pm_info_t *pminfo;
pm_groups_info_t *pm_groups_info;The pm_init subroutine initializes the Performance Monitor API library. It returns, after taking into account a filter on the status of the events, the number of counters available on this processor, and one table per counter with the list of events available. For each event, an event identifier, a status, a flag indicating if the event can be used with a threshold, two names, and a description are provided.
The event identifier is used with all the pm_set_program interfaces and is also returned by all of the pm_get_program interfaces. Only event identifiers present in the table returned can be used. In other words, the filter is effective for all API calls.
The status describes whether the event has been verified, is still unverified, or works with some caveat, as explained in the description. This field is necessary because the filter can be any combination of the three available status bits. The flag points to events that can be used with a threshold.
Only events categorized as verified have gone through full verification. Events categorized as caveat have been verified only within the limitations documented in the event description. Events categorized as unverified have undefined accuracy. Use caution with unverified events; the Performance Monitor software is essentially providing a service to read hardware registers which may or may not have any meaningful content. Users may experiment with unverified event counters and determine for themselves what, if any, use they may have for specific tuning situations.
The short mnemonic name is provided for easy keyword-based search in the event table (see the sample program /usr/samples/pmapi/sysapit2.c for code using mnemonic names). The complete name of the event is also available and a full description for each event is returned.
The structure returned also has the threshold multiplier for this processor and the processor name
On some platforms, it is possible to specify event groups instead of individual events. Event groups are predefined sets of events. Rather than specify each event individually, a single group ID is specified. On some platforms, such as POWER4, use of the event groups is required, and attempts to specify individual events return an error.
The interface to pm_init has been enhanced to return the list of supported event groups in an optional third parameter. For binary compatibilty, the third parameter must be explicitly requested by OR-ing the bitflag, PM_GET_GROUPS, into the filter parameter.
If the pm_groups_info parameter returned by pm_init is NULL, there are no supported event groups for the platform. Otherwise an array of pm_groups_t structures are returned in the event_groups field. The length of the array is given by the max_groups field.
The pm_groups_t structure contains a group identifier, two names and a description that are similar to those of the individual events. In addition, there is an array of integers that specify the events contained in the group.
| Item | Description |
|---|---|
| filter | Specifies which
event types to return.
|
| *pminfo | Returned structure with processor name, threshold multiplier, and a filtered list of events with their current status. |
| *pm_groups_info | Returned structure with list of supported groups. This parameter is only meaningful if PM_GET_GROUPS is OR-ed into the filter parameter. |
| Item | Description |
|---|---|
| 0 | No errors occurred. |
| Positive error code | Refer to the pm_error (pm_error Subroutine) subroutine to decode the error code. |
See the pm_error (pm_error Subroutine) subroutine.
| Item | Description |
|---|---|
| /usr/include/pmapi.h | Defines standard macros, data types, and subroutines. |