[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1


pm_init Subroutine

Purpose

Initializes the Performance Monitor APIs.

Library

Performance Monitor APIs Library (libpmapi.a)

Syntax


#include <pmapi.h>


int pm_init ( filter, *pminfo)
int filter;
pm_info_t *pminfo;

Description

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

Parameters


filter Specifies which event types to return.

PM_VERIFIED
Events which have been verified

PM_UNVERIFIED
Events which have not been verified

PM_CAVEAT
Events which are usable but with caveats as described in the long description
*pminfo Returned structure with processor name, threshold multiplier, and a filtered list of events with their current status.

Return Values


0 No errors occurred.
Positive error code Refer to the pm_error (pm_error Subroutine) subroutine to decode the error code.

Error Codes

Refer to the pm_error (pm_error Subroutine) subroutine.

Files


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

Related Information

pm_error (pm_error Subroutine) subroutine.

Performance Monitor API Programming Concepts in AIX 5L Version 5.1 General Programming Concepts.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]