pm_initialize Subroutine

Purpose

Initializes the Performance Monitor APIs and returns information about a processor.

Library

Performance Monitor APIs Library (libpmapi.a)

Syntax

#include <pmapi.h>

int pm_initialize ( filter,  *pminfo, *pmgroups, proctype)
int filter;
pm_info2_t *pminfo;
pm_groups_info_t *pmgroups;
int proctype;

Description

The pm_initialize subroutine initializes the Performance Monitor API library and retrieves information about a type of processor (if the specified proctype is not PM_CURRENT). It takes into account a filter on the events status, then it returns the number of counters available on this processor and one table per counter containing the list of available events. For each event, it provides an event identifier, a status, two names, and a description. The status contains a set of flags indicating: the event status, if the event can be used with a threshold, if the event is a shared event, and if the event is a grouped-only event.

The event identifier is used with all pm_set_program interfaces and is also returned by all of the pm_get_program interfaces. Only event identifiers present in the returned table 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 been fully verified. Events categorized as caveat have been verified only with the limitations documented in the event description. Events categorized as unverified have an undefined accuracy. Use unverified events cautiously; the Performance Monitor software provides essentially a service to read hardware registers, which might or might not have meaningful content. Users might experiment for themselves with unverified event counters to determine if they can be used for specific tuning situations.

The short mnemonic name is provided for an easy keyword-based search in the event table (see the sample program /usr/samples/pmapi/cpi.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 returned structure also contains the threshold multipliers for this processor, the processor name, and its characteristics. On some platforms, up to three threshold multipliers are available.

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, using event groups is mandatory, and specifying individual events returns an error.

The interface to pm_initialize returns the list of supported event groups in its third parameter. If the pmgroups parameter returned by pm_initialize is NULL, there are no supported event groups for the platform. Otherwise an array of pm_groups_t structures is 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 all similar to those of the individual events. In addition, an array of integers specifies the events contained in the group.

If the proctype parameter is not set to PM_CURRENT, the Performance Monitor APIs library is not initialized, and the subroutine only returns information about the specified processor and those events and groups available in its parameters (pminfo and pmgroups) taking into account the filter. If the proctype parameter is set to PM_CURRENT, in addition to returning the information described, the Performance Monitor APIs library is initialized and ready to accept other calls.

Parameters

Return Values

Error Codes

Refer to the pm_error Subroutine.

Files